home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-03 / advbas9b.zip / ADVBAS.DOC < prev    next >
Text File  |  1990-03-09  |  93KB  |  2,982 lines
  1.              ADVBAS  Copyright (c) 1985-1990  Thomas G. Hanlin III
  2.  
  3.  
  4.                  Advanced Function Library for BASIC Compilers
  5.  
  6.                               ADVBAS v99B, 03/09/90
  7.  
  8.                               Thomas G. Hanlin III
  9.                            3544 E. Southern Ave. #104
  10.                                  Mesa, AZ 85204
  11.  
  12.  
  13.  
  14.  
  15.  
  16. Requirements:
  17.  
  18. An IBM PC/XT/AT/386 or compatible with the Microsoft BASIC compiler v6.x or
  19. QuickBASIC v4.0-4.5.  PC-DOS/MS-DOS versions 2.0 or higher should be used.
  20. Some routines may require a PC-AT or compatible, as noted.  Please read the
  21. Operation Notes for more information on the subject.
  22.  
  23. This library and associated files are protected by copyright.  However, it
  24. may be distributed subject to the restrictions given below.  The source code
  25. is no longer available, although I will still provide support insofar as
  26. regards bug fixes and so forth.
  27.  
  28. While ADVBAS is full-featured and is not crippled in any way, I'd like you to
  29. consider it as a sample of the features contained in the commercial version
  30. of the library, ProBas.  You may use ADVBAS subject to the restrictions
  31. below, but if you find ADVBAS useful, you might well want to upgrade to
  32. ProBas.  The ProBas library comes with tutorial and reference manuals, is a
  33. much more professional product, and contains about four times as many
  34. routines as provided by the ADVBAS library.  See the PROBAS.DOC file for more
  35. information about ProBas and related products.
  36.  
  37.  
  38. Copying and Distribution:
  39.  
  40. The ADVBAS library may be copied and distributed freely under the following
  41. conditions:
  42.  
  43.    1) The source code, if you have it, MAY NOT BE DISTRIBUTED.
  44.  
  45.    2) No fee of over $10.00 U.S. may be charged.  This applies specifically
  46.       to physical copies and is not meant to prevent distribution by
  47.       telecommunications services.
  48.  
  49.    3) All files must be included in their original and unmodified condition.
  50.       This includes ADVBAS.BS, ADVBAS.DOC, ADVBAS.ERR, ADVBAS.LIB,
  51.       ADVBAS.NEW, ADVBAS.QB4, ADVBAS.QRF, ADVBAS.XRF, COMBLINE.BAS,
  52.       FILES.LST, MONKEY.BAS, OBJECT.ZIP, PROBAS.TXT, READ.ME, and XREF.BAS.
  53.  
  54. The copyright is intended to preserve my options and to protect you from the
  55. untoward modifications of others.  It is not intended to prevent the public
  56. distribution of ADVBAS, subject to the above limitations.
  57.  
  58. Caveats:
  59.  
  60. These routines have not caused me any problems and seem to be fully
  61. operational.  However, I will not be responsible for any damages caused by
  62. the use, misuse, or inability to use ADVBAS.  If you run into a problem,
  63. please let me know, and I will do my best to verify and fix the trouble.
  64.  
  65.  
  66. Introduction:
  67.  
  68. The BASIC Compiler is a powerful and flexible tool.  However, it suffers from
  69. a number of limitations.  It is difficult to access many of the capabilities
  70. of DOS, features which require error trapping can't readily be used in
  71. subprograms, and the speed is not all that it might be, for all its
  72. improvement over interpreted BASIC.  The size of compiled programs tends to
  73. be rather excessive as well.
  74.  
  75. In order to reduce these problems, I've designed a number of assembly
  76. language routines which perform various functions and put them in a library
  77. which can be accessed by compiled BASIC programs.  Since I've found these
  78. routines to be useful, I thought I'd pass them on to other people.  You may
  79. use ADVBAS routines in any of your programs, whether commercial, for the
  80. public domain, or simply for your own private use.  I'd appreciate it if you
  81. acknowledged the use of these routines in your program or documentation, but
  82. that is not required.
  83.  
  84.  
  85. Support:
  86.  
  87. Since the release of the commercial version of the library, ProBas, I am not
  88. accepting any further registrations.  Support is hence limited to bug fixes
  89. and so forth, except for previously-registered users.  If you have any
  90. problems, please read this manual.  It probably contains the answer to your
  91. questions.  If not, you can reach me via U.S. mail or the FidoNet QuickBASIC
  92. BBS network.  Please do not phone.
  93.  
  94. Miscellaneous Notes:
  95.  
  96. THE ROUTINES IN THIS VERSION OF ADVBAS ARE NOT ALL COMPATIBLE WITH THOSE IN
  97. PREVIOUS RELEASES OF ADVBAS.
  98.  
  99. This version of the ADVBAS library has been updated specifically to work with
  100. QuickBASIC 4.x.  Due to changes made by Microsoft, the routines that use
  101. arrays must be handled differently.  Any such routines have new calling
  102. conventions, so if you have used the ADVBAS array routines previously, you
  103. will have to modify your programs somewhat.  The new routines will not work
  104. with QuickBASIC versions prior to 4.0.
  105.  
  106. If you need a library that will work with any version of QuickBASIC, rather
  107. than just those versions that ADVBAS supports, you should look into the
  108. ProBas library.  It is designed to work with any IBM or Microsoft version of
  109. the BASIC compiler.  Borland's Turbo BASIC is not supported, as it does not
  110. provide for external libraries.
  111.  
  112. ProBas provides, among other things, routines for sorting, EGA and VGA
  113. graphics, handling of PC Paintbrush graphics files, "long" integer support
  114. (even with compiler versions before QuickBASIC 4.0 and BASCOM 6.0), virtual
  115. screen handling, expanded and extended memory support, and much more.  Add-on
  116. toolkits provide menus (ring, bar, pull-down, pop-up, you name it), btree
  117. file indexing, telecommunications support (file transfers, dialer, script
  118. language, etc), online hypertext help systems, screen design, and just about
  119. anything else you can think of.  For more information, see PROBAS.DOC.
  120.  
  121. Using ADVBAS in the QuickBASIC environment:
  122.  
  123. In order to use ADVBAS inside the QuickBASIC editor/environment, you must
  124. convert the ADVBAS.LIB library to ADVBAS.QLB.  This is done using the LINK
  125. command like this:
  126.  
  127. LINK ADVBAS.LIB/Q,ADVBAS.QLB,NUL,BQLB40.LIB;
  128.  
  129. That's the syntax for QB 4.0.  If you're using QB 4.0b or QB 4.1, change the
  130. last library name to BQLB41.LIB.  If you're using QB 4.5, make it BQLB45.LIB.
  131. If in doubt, just get a DIRectory of your QuickBASIC library files, and use
  132. the name of the BQLBxx.LIB file that appears.
  133.  
  134. Once you have created the ADVBAS.QLB library, you can access the ADVBAS
  135. routines from the QB environment by starting it with the following syntax:
  136.  
  137. QB /L ADVBAS
  138.  
  139. Optionally, you may choose to load your program when you start QuickBASIC.
  140. That looks like this:
  141.  
  142. QB program /L ADVBAS
  143.  
  144. ...where "program" is the name of your BASIC program.
  145.  
  146.  
  147. Note that there is a bug in QuickBASIC 4.0 - 4.1 which causes it to create
  148. unduly large .EXE files when you choose the editor option "compile to EXE".
  149. This does not affect compiling from the command line and is only a problem if
  150. you create your .EXE file from the editor/environment.  This bug was fixed
  151. with the release of QuickBASIC 4.5.
  152.  
  153.  
  154. Compiling from the command line:
  155.  
  156. You can use ADVBAS routines in your program even if you compile from the
  157. command line rather than from within the editor/environment.  To do so,
  158. compile your program as you usually do.  That should look something like:
  159.  
  160. BC program;
  161.  
  162. Next, you LINK the program, but using a special syntax so that the ADVBAS
  163. routines are joined to your program:
  164.  
  165. LINK program,,NUL,ADVBAS;
  166.  
  167. This tells the LINKer that your program uses ADVBAS routines.  LINK will then
  168. search through the ADVBAS library and join the appropriate routines with your
  169. program.  Only the routines that you actually use will become part of your
  170. program.
  171.  
  172. Other languages:
  173.  
  174. The current version of ADVBAS is written using the Microsoft interlanguage
  175. calling conventions.  It should be possible to use most or all ADVBAS
  176. routines with Microsoft C and Microsoft Pascal by making the proper
  177. declarations in your program.  For Microsoft C, tell the compiler that ADVBAS
  178. uses the Pascal calling convention.
  179.  
  180. The Quick C compiler should be able to use ADVBAS in the same way as
  181. Microsoft C.  This does not apply to QuickPascal, however, which (strangely
  182. enough) does not support normal libraries.  Instead, QuickPascal follows
  183. Borland's Turbo Pascal convention and uses "units".  This convention is not
  184. compatible with ADVBAS.
  185.  
  186. BASIC compilers other than those from Microsoft are not supported, since they
  187. do not use the same calling conventions.  I would expect that ADVBAS will
  188. work with C compilers that support the Microsoft calling convention, however.
  189.  
  190.                                 Operation Notes
  191.  
  192.  
  193.  
  194.  
  195. Requirements:
  196.  
  197. Numeric values used with these routines must be integers unless specified
  198. otherwise.  Make sure the variables are integers using DEFINT, or add a
  199. percent sign ("%") to the end of the variable name.  If you use a numeric
  200. expression rather than a variable, it might be a good idea to use the CINT
  201. function to insure that the result is an integer.
  202.  
  203. Strings must sometimes be defined to a certain minimum length, since assembly
  204. language routines are not permitted to change the length of strings.  When
  205. strings are returned, the length of the string will usually also be returned
  206. so that you can convert the result to the appropriate length.  Some strings,
  207. like those containing filenames, must be terminated by a CHR$(0).
  208.  
  209. Arrays require special treatment.  Rather than passing the array directly,
  210. you must pass the segment and offset of the array.  This is accomplished by
  211. using the QuickBASIC VARSEG and VARPTR functions, as described in the
  212. descriptions of the routines which use arrays.  Note that you may use either
  213. Dynamic or Static arrays.  Normal variable-length string arrays cannot be
  214. used, although fixed-length string arrays, user-defined TYPEs, and numeric
  215. arrays are all acceptable.  Just make sure that the array or TYPEd variable
  216. is of an adequate length if you use a routine which expects a specific amount
  217. of storage.  To save the screen with SCRSAVE, for example, you need at least
  218. 4,000 bytes of storage space.  This can be obtained by passing an array or
  219. TYPEd variable dimensioned in any of the following ways:
  220.  
  221. DIM Scrn%(1 TO 2000)         ' 4,000 bytes of integer storage
  222. DIM Scrn&(1 TO 1000)         ' 4,000 bytes of long integer storage
  223. DIM Scrn AS STRING * 4000    ' 4,000 bytes of fixed-length string storage
  224.  
  225.  
  226. Compatibility:
  227.  
  228. These functions vary in what they demand of your computer.  Some functions
  229. will work only on true clones, some will work on near clones, and some will
  230. work on any MS-DOS machine.  The compatibility level of each function is
  231. listed using the categories CLONE (will work on hardware compatibles only),
  232. BIOS (close compatibles only), DOS (any MS-DOS machine), and ANY (hardware
  233. independent).  Note that the BASIC compiler itself does not produce very
  234. compatible code (BASIC video routines are CLONE level, for example), so
  235. you should have no problems with ADVBAS compatibility if you can use the
  236. BASIC compiler.
  237.  
  238.                               Routine Reference
  239.  
  240.  
  241.  
  242. Disk:
  243.    CopyFile     copy a file
  244.    DelSub       delete a subdirectory
  245.    DiskStat     retrieve assorted disk status information
  246.    DrvSpace     get the space left on a given drive
  247.    Exist        see if a file exists
  248.    FClose       close a file
  249.    FCreate      create a file
  250.    FindFirstF   find the first file matching a wildcard specification
  251.    FindNextF    find additional files after FindFirstF
  252.    FOpen        open a file
  253.    FRead        read from a file
  254.    FSetEnd      move to the end of a file
  255.    FSetRec      move to a specific point in a file
  256.    GetAttrF     get the attribute of a file found by FindFirstF/FindNextF
  257.    GetDateF     get the date of a file found by FindFirstF/FindNextF
  258.    GetDrv       get the default drive
  259.    GetFAttr     get the attribute of a file
  260.    GetFDate     get the date of a file
  261.    GetFTime     get the time of a file
  262.    GetNameF     get the name of a file found by FindFirstF/FindNextF
  263.    GetSizeF     get the size of a file found by FindFirstF/FindNextF
  264.    GetSub       get the default subdirectory
  265.    GetTimeF     get the time of a file found by FindFirstF/FindNextF
  266.    MakeSub      create a subdirectory
  267.    MLoad        a fast version of the BLOAD statement
  268.    SetDrv       set the default drive
  269.    SetFTD       set the time and date of a file
  270.    SetFAttr     set the attribute of a file
  271.    SetSub       set the default subdirectory
  272.    SubExist     see if a subdirectory exists
  273.  
  274. Input:
  275.    ClrKbd       clear the keyboard buffer
  276.    DosInkey     get a key using DOS standard input
  277.    GetKbd       get the state of the keyboard toggles
  278.    GetKey       get one of a list of valid keys
  279.    KeyPress     see if a key has been pressed
  280.    MmButton     see if the mouse buttons are being pressed
  281.    MmCheck      see if a mouse is available
  282.    MmClick      see if the mouse buttons were pressed since last checked
  283.    MmCursorOff  make the mouse cursor invisible
  284.    MmCursorOn   make the mouse cursor visible
  285.    MmGetLoc     get the location of the mouse cursor
  286.    MmSetLoc     set the location of the mouse cursor
  287.    MmSetRange   set the range for the mouse cursor
  288.    SetKbd       set the state of the keyboard toggles
  289.  
  290.                               Routine Reference
  291.  
  292.  
  293.  
  294. String:
  295.    BSq          compress a text string
  296.    BUsq         uncompress a string
  297.    BUsqLen      see how long a compressed string will be when expanded
  298.    Checksum     calculate an Xmodem/Ymodem checksum
  299.    CRC          calculate an Xmodem/Ymodem CRC
  300.    Crunch       remove duplicates of a character from a string
  301.    DateN2S      convert a date from numbers to a string
  302.    DateS2N      convert a date from a string to numbers
  303.    Extract      extract a substring from within a delimited string
  304.    LoCase       convert the letters in a string to lowercase
  305.    LRotate      rotate the characters in a string left
  306.    MultiAnd     perform an arithmetic AND operation on each char in a string
  307.    MultiOr      perform an arithmetic OR operation on each char in a string
  308.    MultiXor     perform an arithmetic XOR operation on each char in a string
  309.    Reverse      reverse the characters in a string
  310.    RRotate      rotate the characters in a string right
  311.    Soundex      get the Soundex code for a string (for sound-alike matching)
  312.    StripBlanks  remove leading and/or trailing blanks from a string
  313.    Strip        remove occurrences of a specific character from a string
  314.    StripRange   remove occurrences of a range of characters from a string
  315.    TimeN2S      convert a time from numbers to a string
  316.    TimeS2N      convert a time from a string to numbers
  317.    Tinstr       find a given type of character within a string
  318.    UpCase       convert the letters in a string to uppercase
  319.    Xlate        translate the characters of a string using a table
  320.  
  321.  
  322. Array:
  323.    AddMatI      add a value to selected elements of an integer array
  324.    ReadBitF     get a number from an array of arbitrary bit length
  325.    SetMatI      set selected elements of an integer array to a specific value
  326.    WriteBitF    put a number into an array of arbitrary bit length
  327.  
  328.                               Routine Reference
  329.  
  330.  
  331.  
  332. Video:
  333.    BkScroll     scroll any part of the screen down, or clear it
  334.    BkSpace      destructive backspace
  335.    CalcAttr     calculate color/attribute from foreground and background colors
  336.    ClrEOL       clear from the cursor to the end of the line
  337.    DelChr       delete a character
  338.    DmPrint      display a string using DOS output
  339.    GetCRT       get display type (mono or color)
  340.    GetLine      retrieve a specified line from a saved screen
  341.    GetScreen    save any part of any display page to a buffer
  342.    InsChr       insert a space
  343.    MakeWindow   display a pop-up window
  344.    MDelChr      delete a character from a window defined by MWindow
  345.    MInsChr      insert a space into a window defined by MWindow
  346.    MPrint       display a string to a window defined by MWindow
  347.    MPrintC      display a character to a window defined by MWindow
  348.    MWindow      define the range for certain display operations
  349.    PrintScreen  print out the display to the default printer
  350.    QPrint       display a string very quickly using machine-level access
  351.    ReColor      change everything of a specific color to another color
  352.    ResetPoint   clear a point (low-resolution text-mode graphics)
  353.    Scroll       scroll any part of the screen up, or clear it
  354.    ScrRest      restore a saved screen to the display
  355.    ScrRestP     restore a saved screen to a specific display page (no snow)
  356.    ScrRestPD    restore a saved screen to a specific display page
  357.    ScrSave      save the contents of the screen to a buffer
  358.    ScrSaveP     save a specific display page to a buffer (no snow)
  359.    ScrSavePD    save a specific display page to a buffer
  360.    SetPoint     set a point (low-resolution text-mode graphics)
  361.    TestPoint    test a point (low-resolution text-mode graphics)
  362.    XQPrint      display a string very quickly using machine-level access
  363.  
  364.  
  365. Miscellaneous:
  366.    Any2Dec      convert from any base to decimal
  367.    BlockMove    move data from one area of memory to another
  368.    Carrier      get the state of the modem Carrier Detect signal
  369.    DataSeg      get the default Data Segment
  370.    Date2Int     compress a date into an integer
  371.    Dec2Any      convert from decimal to any base
  372.    Delay        delay for a given number of seconds
  373.    Delay18th    delay for a given number of eighteenths of seconds
  374.    DTR          set the state of the comm port's DTR signal
  375.    Equipment    get hardware info about memory and installed ports
  376.    GetDOSv      get the current DOS version
  377.    GetExtM      get the amount of extended memory (AT systems only)
  378.    GetLIMm      get the amount of expanded memory installed and available
  379.    Int2Date     uncompress a date from an integer
  380.    Int2Time     uncompress a time from an integer
  381.    Month        get the name of a month
  382.    SetComm      set up comm parameters without closing the comm port
  383.    ShiftL       shift the bits in an integer left
  384.    ShiftR       shift the bits in an integer right
  385.    Speaker      turn sound effects on or off
  386.    Time2Int     compress a time into an integer
  387.    WeekDay      get the day of the week
  388.  
  389.                               Compatibility Chart
  390.  
  391.  
  392.  
  393.  
  394. The following will work on ANY machine:
  395.  
  396. AddMatI, Any2Dec, BlockMove, Bsq, BUsq, BUsqLen, CalcAttr, Checksum, CRC,
  397. Crunch, DataSeg, Date2Int, Dec2Any, Extract, GetLine, Int2Date, Int2Time,
  398. LoCase, LRotate, Month, MultiAND, MultiOR, MultiXOR, ReadBitF, Reverse,
  399. RRotate, SetMatI, ShiftL, ShiftR, Soundex, Strip, StripBlanks, StripRange,
  400. Time2Int, TInstr, UpCase, WriteBitF, Xlate
  401.  
  402.  
  403. The following will work on machines that can run DOS:
  404.  
  405. CopyFile, DelSub, DiskStat, DmPrint, DOSInkey, DrvSpace, Exist, FClose,
  406. FCreate, FindFirstF, FindNextF, FOpen, FRead, FSetEnd, FSetRec, FWrite,
  407. GetAttrF, GetDateF, GetDOSv, GetDrv, GetFAttr, GetFDate, GetFTime, GetNameF,
  408. GetSizeF, GetSub, GetTimeF, MakeSub, MLoad, SetDrv, SetFAttr, SetFTD, SetSub,
  409. SubExist, WeekDay
  410.  
  411.  
  412. The following will work on machines with a PC-type BIOS (* for AT BIOS):
  413.  
  414. BkScroll, BkSpace, ClrKbd, ClrEOL, DateN2S, DateS2N, Delay, Delay18th,
  415. Equipment, GetCRT, GetExtM*, GetKey, GetLIMm, Keypress, MDelChr, MInsChr,
  416. MmButton, MmCheck, MmClick, MmCursorOff, MmCursorOn, MmGetLoc, MmSetLoc,
  417. MmSetRange, MPrint, MPrintC, MWindow, PrintScreen, ResetPoint, SetPoint,
  418. Scroll, TestPoint, TimeN2S, TimeS2N, XmPrint
  419.  
  420.  
  421. The following will work only on true PC compatibles:
  422.  
  423. Carrier, DelChr, DTR, GetKbd, GetScreen, InsChr, MakeWindow, PutScreen,
  424. QPrint, ReColor, ScrRest, ScrRestP, ScrRestPD, ScrSave, ScrSaveP, ScrSavePD,
  425. SetComm, SetKbd, Speaker, XQPrint, XQPrintD
  426.  
  427.  
  428.  
  429. Note that routines from higher sections will work on machines from lower
  430. sections (DOS-level routines will work on BIOS-level and CLONE-level
  431. machines).  It doesn't work the other way around (CLONE-level routines may
  432. not work on a DOS-level machine).
  433.  
  434. Name: AddMatI
  435.  
  436. Type: Miscellaneous / ANY
  437.  
  438. Description:
  439.    Adds a scalar (integer) value to an integer array.  You can subtract by
  440.    adding a negative number.  If the results of the calculation ever go
  441.    outside integer range (-32768 to 32767), the overflow flag is set on
  442.    return.  See SETMATI for more information.
  443.  
  444. Example:
  445.    DIM Array%(1 TO 10000)
  446.    ' presumably you set Array%() to something here
  447.    ArraySize% = UBOUND(Array%) - LBOUND(Array%) + 1
  448.    DSeg% = VARSEG(Array%(LBOUND(Array%)))
  449.    DOfs% = VARPTR(Array%(LBOUND(Array%)))
  450.    AddValue% = -6
  451.    CALL AddMatI(DSeg%, DOfs%, ArraySize%, AddValue%, Overflow%)
  452.    IF Overflow% THEN PRINT "Error: overflow during array operation"
  453.  
  454.  
  455.  
  456.  
  457. Name: Any2Dec
  458.  
  459. Type: Miscellaneous / ANY
  460.  
  461. Description:
  462.    Converts a number (in string form) from any base (2-35) to a decimal
  463.    integer (base 10).  The number to be converted may be in either signed
  464.    integer range (-32768 to 32767) or unsigned integer range (0 to 65535).
  465.    It is converted to a signed integer, since BASIC doesn't have an unsigned
  466.    integer type.  If you would prefer to treat the results as an unsigned
  467.    integer, use a long integer value to receive the result, after setting it
  468.    to zero.
  469.  
  470. Example:
  471.    ' for a signed integer result, do this:
  472.    INPUT "Number, base of number"; Number$, NumBase%
  473.    CALL Any2Dec(Number$, NumBase%, Result%, ErrCode%)
  474.    IF ErrCode% THEN
  475.       PRINT "Invalid number for specified base"
  476.    ELSE
  477.       PRINT "In decimal, that number is: "; Result%
  478.    END IF
  479.  
  480.    ' for an unsigned result, do this:
  481.    INPUT "Number, base of number"; Number$, NumBase%
  482.    Result& = 0
  483.    CALL Any2Dec(Number$, NumBase%, Result&, ErrCode%)
  484.    IF ErrCode% THEN
  485.       PRINT "Invalid number for specified base"
  486.    ELSE
  487.       PRINT "In decimal, that number is: "; Result&
  488.    END IF
  489.  
  490. Name: BkScroll
  491.  
  492. Type: Video / BIOS
  493.  
  494. Description:
  495.    Scrolls any selected part of the screen down by a specified number of
  496.    lines.  If you tell it to scroll zero lines, the specified area will be
  497.    cleared instead.
  498.  
  499. Example:
  500.    TopRow% = 1
  501.    LeftCol% = 1
  502.    BottomRow% = 25
  503.    RightCol% = 80
  504.    Times% = 2
  505.    CALL BkScroll(LeftCol%, TopRow%, RightCol%, BottomRow%, Times%)
  506.    ' scrolls the entire screen down two lines
  507.  
  508.  
  509.  
  510.  
  511. Name: BkSpace
  512.  
  513. Type: Video / BIOS
  514.  
  515. Description:
  516.    This is a "destructive backspace" routine.  It deletes the previous
  517.    character and moves the cursor back one space.  If the cursor was at the
  518.    beginning of a line, it will wrap up to the end of the previous line if
  519.    there is one.  Since QuickBASIC may not recognize the change of cursor
  520.    position, the new cursor position is returned so that you can use the
  521.    LOCATE statement.
  522.  
  523. Example:
  524.    CALL BkSpace(Col%, Row%)    ' note that the coordinates are backward!
  525.    LOCATE Row%, Col%
  526.  
  527.  
  528.  
  529.  
  530. Name: BlockMove
  531.  
  532. Type: Miscellaneous / ANY
  533.  
  534. Description:
  535.    Copies information from one area of memory to another.  Due to certain
  536.    convolutions involved, it is not recommended that you use this routine
  537.    unless you have a very good idea of what you're doing.  It isn't as easy
  538.    as it looks!  Specify a direction of zero to move forward from the
  539.    specified addresses, or a nonzero direction to move backward from the
  540.    specified addresses.
  541.  
  542. Example:
  543.    FromSeg% = &HB800     ' location of CGA text page 0
  544.    FromOfs% = 0
  545.    ToSeg% = &HB800       ' location of CGA text page 1
  546.    ToOfs% = &H1000
  547.    Bytes% = 4000         ' 4,000 bytes per 80x25 screen
  548.    Direction% = 0        ' increment addresses as we move
  549.    CALL BlockMove(FromSeg%, FromOfs%, ToSeg%, ToOfs%, Bytes%, Direction%)
  550.    ' we just copied CGA page 0 to page 1
  551.  
  552. Name: BSq
  553.  
  554. Type: String / ANY
  555.  
  556. Description:
  557.    Reduces the length of text strings by using several techniques to compress
  558.    blanks.  The strings may not be longer than 127 characters or contain IBM
  559.    ASCII characters (from CHR$(128) to CHR$(255)).  The result will be a
  560.    string that is printable, if odd looking (it will contain IBM ASCII
  561.    codes, which normally show up as graphics characters).  Space savings
  562.    range from about 16% on normal text to 50% or more for strings which
  563.    contain many spaces.  The resulting string might be the same length, if it
  564.    didn't contain any blanks, but it will never be longer than the original.
  565.  
  566. Example:
  567.    INPUT "String to squeeze"; St$
  568.    CALL BSq(St$, SLen%)
  569.    PRINT "Squeezed string: "; LEFT$(St$, SLen%)
  570.  
  571.  
  572.  
  573.  
  574. Name: BUsq
  575.  
  576. Type: String / ANY
  577.  
  578. Description:
  579.    Unsqueezes a string that was compressed by BSq.  Use the BUsqLen routine
  580.    beforehand to find out how long the resulting string will be.
  581.  
  582. Example:
  583.    see the BUsqLen routine
  584.  
  585.  
  586.  
  587.  
  588. Name: BUsqLen
  589.  
  590. Type: String / ANY
  591.  
  592. Description:
  593.    Tells how long a string compressed by BSq will be, once it is unsqueezed.
  594.    This is necessary before unsqueezing the string with BUsq.
  595.  
  596. Example:
  597.    CALL BUsqLen(St$, SLen%)
  598.    IF SLen% < 0 THEN
  599.       PRINT "Error: string was not compressed or is damaged"
  600.    ELSE
  601.       Unsq$ = SPACE$(SLen%)
  602.       CALL BUsq(St$, Unsq$)
  603.    END IF
  604.  
  605. Name: CalcAttr
  606.  
  607. Type: Video / ANY
  608.  
  609. Description:
  610.    Calculates the color/attribute for certain display routines, such as
  611.    XQPrint.  A color/attribute is a single byte that combines the foreground
  612.    and background colors together.  It represents the way colors are handled
  613.    by the computer at the BIOS and direct machine level.
  614.  
  615. Example:
  616.    ForeGround% = 15     ' bright white foreground color
  617.    BackGround% = 0      ' black background color
  618.    CALL CalcAttr(ForeGround%, BackGround%, Attr%)
  619.  
  620.  
  621.  
  622.  
  623. Name: Carrier
  624.  
  625. Type: Miscellaneous / CLONE
  626.  
  627. Description:
  628.    Returns the status of the modem Carrier Detect signal.  You may specify
  629.    communications port one or two.
  630.  
  631. Example:
  632.    CommPort% = 1
  633.    CALL Carrier(CommPort%, CD%)
  634.    IF CD% THEN
  635.       PRINT "Carrier detected"
  636.    ELSE
  637.       PRINT "No carrier"
  638.    END IF
  639.    ' Note: we don't use the variable Carrier% as QuickBASIC would complain.
  640.    ' QB doesn't like it when variables and routines have the same name.
  641.  
  642.  
  643.  
  644.  
  645. Name: CopyFile
  646.  
  647. Type: Disk / DOS
  648.  
  649. Description:
  650.    Copies a file.  This is faster than the DOS command and doesn't have the
  651.    overhead of using the SHELL statement.  You might want to use the Exist
  652.    routine to see if the destination file exists beforehand, in order to
  653.    avoid accidentally copying over an existing file.
  654.  
  655. Example:
  656.    SourceFile$ = "A:EXAMPLE.TXT"
  657.    DestFile$ = "C:\DOCUMENT\EXAMPLE.TXT"
  658.    CALL CopyFile(SourceFile$ + CHR$(0), DestFile$ + CHR$(0), ErrCode%)
  659.    IF ErrCode% THEN
  660.       PRINT "Error: copy failed"
  661.       ' this will usually be due to a nonexistent source file
  662.       ' or to running out of space on the destination disk
  663.    END IF
  664.  
  665. Name: Checksum
  666.  
  667. Type: Miscellaneous / ANY
  668.  
  669. Description:
  670.    Calculates a checksum for a string.  This is the same checksum as used by
  671.    the standard Xmodem file transfer protocol.  It will also work with any
  672.    proper implementation of Ymodem.
  673.  
  674. Example:
  675.    CALL Checksum(St$, Chk%)
  676.  
  677.  
  678.  
  679.  
  680. Name: ClrEOL
  681.  
  682. Type: Video / BIOS
  683.  
  684. Description:
  685.    Clears from the cursor position to the end of the current screen row,
  686.    inclusive.  The cursor is not moved.
  687.  
  688. Example:
  689.    CALL ClrEOL
  690.  
  691.  
  692.  
  693.  
  694. Name: ClrKbd
  695.  
  696. Type: Input / BIOS
  697.  
  698. Description:
  699.    Clears the keyboard buffer.  Any keys which were waiting to be processed
  700.    will be gone.  This is a particularly useful routine to use before an
  701.    input routine used to clear up an error condition, for example.  It
  702.    insures that keys waiting in the type-ahead buffer do not unexpectedly
  703.    answer for the user.
  704.  
  705. Example:
  706.    CALL ClrKbd
  707.    INPUT "File does not exist.  Create it (Y/N)"; YN$
  708.  
  709. Name: CRC
  710.  
  711. Type: Miscellaneous / ANY
  712.  
  713. Description:
  714.    Calculates a CRC (Cyclical Redundancy Check) for a string.  This is used
  715.    for error detection.  The algorithm used is compatible with the Xmodem CRC
  716.    and Ymodem CRC file transfer protocols.
  717.  
  718. Example:
  719.    ' sending an Xmodem or Ymodem record (St$ is the data part):
  720.    CALL CRC(St$ + STRING$(2, 0), HiCRC%, LoCRC%)
  721.    St$ = St$ + CHR$(HiCRC%) + CHR$(LoCRC%)
  722.  
  723.    ' receiving an Xmodem or Ymodem record:
  724.    ' (St$ is the data part plus the received CRC)
  725.    CALL CRC(St$, HiCRC%, LoCRC%)
  726.    IF HiCRC% = 0 AND LoCRC% = 0 THEN
  727.       St$ = LEFT$(St$, LEN(St$) - 2)   ' trim off received CRC
  728.       GoodRecord = -1                  ' flag it as a good record
  729.    ELSE
  730.       GoodRecord = 0                   ' flag it as a bad record
  731.    END IF
  732.  
  733.  
  734.  
  735.  
  736. Name: Crunch
  737.  
  738. Type: String / ANY
  739.  
  740. Description:
  741.    Crunches duplicates of a given character in a string down to a single
  742.    character.  This is a good way to get input into a regular format,
  743.    especially when combined with the StripBlanks routine.
  744.  
  745. Example:
  746.    St$ = "This    is a  test"
  747.    Ch$ = " "
  748.    CALL Crunch(St$, Ch$, SLen%)
  749.    St$ = LEFT$(St$, SLen%)
  750.    ' the result here will be "This is a test"
  751.  
  752.  
  753.  
  754.  
  755. Name: DataSeg
  756.  
  757. Type: Miscellaneous / ANY
  758.  
  759. Description:
  760.    Gets the default data segment, which is used by BASIC for storing
  761.    variable-length strings.  It is also used for storing static arrays,
  762.    except when in the QB editor/environment.  This can be handy in
  763.    conjunction with the BlockMove routine.
  764.  
  765. Example:
  766.    CALL DataSeg(DSeg%)
  767.  
  768. Name: Date2Int
  769.  
  770. Type: Miscellaneous / ANY
  771.  
  772. Description:
  773.    Compresses a date into an integer.  The date is assumed to be valid.  The
  774.    year should be within the range 1900 - 2026 (or 0 - 99, which is assumed
  775.    to represent 1900 - 1999).  The resulting compressed date is not in
  776.    "Julian" form (performing mathematical operations on it will not get you
  777.    anywhere).
  778.  
  779. Example:
  780.    CALL Date2Int(Mnth%, Day%, Year%, Result%)
  781.    ' we abbreviate the month since there is a routine named Month and
  782.    ' QuickBASIC would complain if we had a variable by the same name.
  783.  
  784.  
  785.  
  786.  
  787. Name: DateN2S
  788.  
  789. Type: String / ANY
  790.  
  791. Description:
  792.    Converts a date from numeric form to a string.  The year may be any
  793.    non-negative number.  You must reserve at least eight characters for the
  794.    string.
  795.  
  796. Related routines:
  797.    DateS2N, TimeN2S, TimeS2N
  798.  
  799. Example:
  800.    Mnth% = 3
  801.    ' we abbreviate the month since there is a routine named Month and
  802.    ' QuickBASIC would complain if we had a variable by the same name.
  803.    Day% = 2
  804.    Year% = 1987      ' 87 would do as well
  805.    Result$ = SPACE$(8)
  806.    CALL DateN2S(Mnth%, Day%, Year%, Result$)
  807.    ' the result from this will be "03/02/87"
  808.    ' if you prefer the form "03-02-87", add the following:
  809.    MID$(Result$, 3, 1) = "-"
  810.    MID$(Result$, 6, 1) = "-"
  811.  
  812.  
  813.  
  814.  
  815. Name: DATES2N
  816.  
  817. Type: String / ANY
  818.  
  819. Description:
  820.    Converts a date from a string to numeric form.  The date string may be in
  821.    either the BASIC format ("02-01-1990") or the usual format ("02/01/90").
  822.  
  823. Example:
  824.    CALL DateS2N(Mnth%, Day%, Year%, DATE$)
  825.    ' we abbreviate the month since there is a routine named Month and
  826.    ' QuickBASIC would complain if we had a variable by the same name.
  827.  
  828. Name: Dec2Any
  829.  
  830. Type: Miscellaneous / ANY
  831.  
  832. Description:
  833.    Converts a number to any reasonable base (2-35).  The number will be
  834.    converted to an unsigned integer, in keeping with the operation of the
  835.    BASIC functions HEX$ and OCT$.  It is recommended that you set the result
  836.    string to at least 16 characters, which is the maximum possible length
  837.    that can be returned by this routine.  The result will be right-justified
  838.    in the string that you provided, so if you want leading zeroes, just set
  839.    the initial string to zeroes and ignore the returned length specification.
  840.  
  841. Example:
  842.    INPUT "Decimal number, to base"; Number%, NumBase%
  843.    Result$ = STRING$(16, "0")
  844.    CALL Dec2Any(Number%, NumBase%, Result$, RLen%)
  845.    IF RLen% < 0 THEN
  846.       PRINT "Error: invalid base or insufficient room in result string"
  847.    ELSE
  848.       Result$ = RIGHT$(Result$, RLen%)
  849.       PRINT "Result: "; Result$
  850.    END IF
  851.  
  852.  
  853.  
  854.  
  855. Name: Delay
  856.  
  857. Type: Miscellaneous / BIOS
  858.  
  859. Description:
  860.    Delays for a specified number of seconds.  This is based on the system
  861.    clock, so it will delay for the same amount of time no matter how fast
  862.    your computer may be.  It is normally accurate to within 1/18th second,
  863.    although it may take longer if multitasking is going on.
  864.  
  865. Example:
  866.    Seconds% = 60
  867.    CALL Delay(Seconds%)     ' delay for one minute
  868.  
  869.  
  870.  
  871.  
  872. Name: Delay18th
  873.  
  874. Type: Miscellaneous / BIOS
  875.  
  876. Description:
  877.    Delays for a specified number of 18ths of a second.  This is based on the
  878.    system clock, so it will delay for the same amount of time no matter how
  879.    fast your computer may be.  It is normally accurate to within 1/18th
  880.    second, although it may take longer if multitasking is going on.
  881.  
  882. Example:
  883.    SmallDelay% = 9
  884.    CALL Delay18th(SmallDelay%)     ' delay for 1/2 second
  885.  
  886. Name: DelChr
  887.  
  888. Type: Video / CLONE
  889.  
  890. Description:
  891.    Deletes the character at the specified screen location.  All characters to
  892.    the right of it on the same row will be shifted left to fill the vacated
  893.    space.  This works only in text mode (SCREEN 0) on display page zero.
  894.  
  895. Example:
  896.    Row% = CSRLIN
  897.    Col% = POS(0)
  898.    CALL DelChr(Row%, Col%)       ' delete the character at the cursor
  899.  
  900.  
  901.  
  902.  
  903. Name: DelSub
  904.  
  905. Type: Disk / DOS
  906.  
  907. Description:
  908.    Deletes a subdirectory.  Note that you may not delete a subdirectory if
  909.    there are any files in it or if it is the current directory.  The root
  910.    directory may never be deleted.
  911.  
  912. Example:
  913.    CALL DelSub(SubDir$ + CHR$(0), ErrCode%)
  914.    IF ErrCode% THEN
  915.       PRINT "Error: unable to delete subdirectory "; SubDir$
  916.    END IF
  917.  
  918.  
  919.  
  920.  
  921. Name: DiskStat
  922.  
  923. Type: Disk / DOS
  924.  
  925. Description:
  926.    Gets various status information about a given disk drive.  You may use an
  927.    at-sign ("@") to specify the default drive.  The information returned will
  928.    be free clusters, total clusters, bytes per sector, and sectors per
  929.    cluster.  From this, you can calculate the amount of space left on the
  930.    disk, the amount of space used, and so forth.
  931.  
  932. Example:
  933.    Drive$ = "C"
  934.    CALL DiskStat(Drive$, FreeClus%, TotClus%, BytesPerSec%, SecsPerClus%)
  935.    FreeSpace& = CLNG(FreeClus%) * CLNG(BytesPerSec%) * CLNG(SecsPerClus%)
  936.    TotalSpace& = CLNG(TotClus%) * CLNG(BytesPerSec%) * CLNG(SecsPerClus%)
  937.    PRINT "Information for drive "; Drive$; ":"
  938.    PRINT "  Total bytes:"; TotalSpace&
  939.    PRINT "  Bytes free :"; FreeSpace&
  940.    PRINT "  Bytes used :"; TotalSpace& - FreeSpace&
  941.  
  942. Name: DmPrint
  943.  
  944. Type: Video / DOS
  945.  
  946. Description:
  947.    Displays a string at the current cursor position, using DOS display
  948.    methods.  This allows full redirection (unlike PRINT, this routine will
  949.    work properly with windowing multitaskers and CTTY), use of ANSI.SYS, and
  950.    so forth.  Control codes are largely treated in the standard ASCII way
  951.    rather than the way BASIC handles them.  The cursor position may or may
  952.    not be updated, depending on your version of QuickBASIC.
  953.  
  954. Example:
  955.    CALL DmPrint(St$)
  956.  
  957.  
  958.  
  959.  
  960. Name: DOSInkey
  961.  
  962. Type: Keyboard / DOS
  963.  
  964. Description:
  965.    Like INKEY$, but gets a key from the standard input device.  This is
  966.    normally the keyboard, but it may be redirected to a file or to a comm
  967.    port (using CTTY).  Two parameters are returned.  The first gives the key
  968.    code, if any, and the second gives status information.  See example.
  969.  
  970. Example:
  971.    CALL DOSInkey(ChrCode%, ChrType%)
  972.    IF ChrType% = 0 THEN
  973.       PRINT "No key is pressed"
  974.    ELSEIF ChrType% = 1 THEN
  975.       PRINT "The "; CHR$(ChrCode%); " key was pressed."
  976.    ELSE
  977.       PRINT "An extended key was pressed.  The code is "; ChrCode%
  978.       ' this will happen for function keys, ALT key combinations, etc
  979.       ' ChrCode% is the same as the right char of a two-char INKEY$ string
  980.    END IF
  981.  
  982.  
  983.  
  984.  
  985. Name: DrvSpace
  986.  
  987. Type: Disk / DOS
  988.  
  989. Description:
  990.    Gets the amount of free space remaining on the specified drive.  You may
  991.    use an at-sign ("@") to specify the default drive.  See also DiskStat.
  992.  
  993. Example:
  994.    Drive$ = "@"                      ' use the default drive
  995.    CALL DrvSpace(Drive$, A%, B%, C%)
  996.    FreeSpace& = CLNG(A%) * CLNG(B%) * CLNG(C%)
  997.  
  998. Name: DTR
  999.  
  1000. Type: Miscellaneous / CLONE
  1001.  
  1002. Description:
  1003.    Turns the communications signal DTR (Data Terminal Ready) on or off.
  1004.    Turning the DTR off is a reliable way of making most modems drop carrier
  1005.    (hang up the phone).  Use zero to turn off the DTR, or nonzero to turn it
  1006.    back on.  The comm port must be one or two.
  1007.  
  1008. Example:
  1009.    CommPort% = 1
  1010.    DTRstate% = 0                 ' turn off the DTR
  1011.    CALL DTR(CommPort%, DTRstate%)
  1012.  
  1013.  
  1014.  
  1015.  
  1016. Name: Equipment
  1017.  
  1018. Type: Miscellaneous / BIOS
  1019.  
  1020. Description:
  1021.    Gets information about the basic hardware configuration of the computer:
  1022.    base memory, parallel ports, serial ports, and game ports.  Note that some
  1023.    computers will not return accurate information about the game port.
  1024.  
  1025. Example:
  1026.    CALL Equipment(KBytes%, Parallel%, Serial%, Game%)
  1027.  
  1028.  
  1029.  
  1030.  
  1031. Name: Exist
  1032.  
  1033. Type: Disk / DOS
  1034.  
  1035. Description:
  1036.    Sees if a specified file exists.  You may prefer to use the FindFirstF
  1037.    routine instead if you are operating in a multitasking or network
  1038.    environment, to avoid possible conflicts.
  1039.  
  1040. Example:
  1041.    CALL Exist(File$ + CHR$(0), FileExists%)
  1042.    IF FileExists% THEN PRINT "File already exists"
  1043.  
  1044. Name: Extract
  1045.  
  1046. Type: String / ANY
  1047.  
  1048. Description:
  1049.    Extracts a substring from a delimited string.  You must specify which of
  1050.    the delimited substrings to return (1-256) and the delimiter character.
  1051.    A pointer to the start of the substring and the length of the substring
  1052.    will be returned.
  1053.  
  1054. Example:
  1055.    St$ = "John Doe/15 Maple Rd/Hometown, CA 99199/(300) 111-1111"
  1056.    Index% = 2
  1057.    Delimiter$ = "/"
  1058.    CALL Extract(St$, Delimiter$, Index%, Start%, SLen%)
  1059.    PRINT MID$(St$, Start%, SLen%)
  1060.    ' this will print "15 Maple Rd"
  1061.  
  1062.  
  1063.  
  1064.  
  1065. Name: FClose
  1066.  
  1067. Type: Disk / DOS
  1068.  
  1069. Description:
  1070.    Closes a file that was opened using the FOpen routine.
  1071.  
  1072. Related routines:
  1073.    FCreate, FOpen, FRead, FSetEnd, FSetRec, FWrite
  1074.  
  1075. Example:
  1076.    CALL FClose(Handle%)
  1077.  
  1078.  
  1079.  
  1080.  
  1081. Name: Fcreate
  1082.  
  1083. Type: Disk / DOS
  1084.  
  1085. Description:
  1086.    Creates a file with the specified attribute and opens it for read/write
  1087.    access.  If the file already existed, it's set to zero bytes in length.
  1088.    The file attribute may be zero, to create a normal file, or two, to create
  1089.    a hidden file.  If there is no error, a "handle" is returned with which
  1090.    you can access the file using other ADVBAS routines.
  1091.  
  1092. Related routines:
  1093.    FOpen, FRead, FSetEnd, FSetRec, FWrite
  1094.  
  1095. Example:
  1096.    Attr% = 0     ' normal file
  1097.    CALL FCreate(File$ + CHR$(0), Attr%, Handle%, ErrCode%)
  1098.    IF ErrCode% THEN PRINT "Error: unable to create file "; File$
  1099.  
  1100. Name: FindFirstF
  1101.  
  1102. Type: Disk / DOS
  1103.  
  1104. Description:
  1105.    Finds the first file to match the file specification and search attribute
  1106.    that you give it.  The file specification may contain a drive and
  1107.    directory.  Wildcards are permitted.  If there is no matching file,
  1108.    ErrCode% will be nonzero.
  1109.  
  1110.    The search attribute may be any combination of the following:
  1111.       0    normal files
  1112.       2    hidden and normal files
  1113.       4    system and normal files
  1114.      16    subdirectories and normal files
  1115.  
  1116.    Add the desired attributes together to produce the search attribute.  You
  1117.    may retrieve various information about any matching file (see below).
  1118.  
  1119. Related routines:
  1120.    FindNextF, GetAttrF, GetDateF, GetNameF, GetSizeF, GetTimeF
  1121.  
  1122. Example:
  1123.    File$ = "*.*"     ' match any file
  1124.    Attr% = 16+2      ' seek subdirectories, hidden and normal files
  1125.    CALL FindFirstF(File$ + CHR$(0), Attr%, ErrCode%)
  1126.    IF ErrCode% THEN PRINT "No matching files"
  1127.  
  1128.  
  1129.  
  1130.  
  1131. Name: FindNextF
  1132.  
  1133. Type: Disk / DOS
  1134.  
  1135. Description:
  1136.    This is used after the FindFirstF routine in order to find further
  1137.    matching files.
  1138.  
  1139. Related routines:
  1140.    FindFirstF, GetAttrF, GetDateF, GetNameF, GetSizeF, GetTimeF
  1141.  
  1142. Example:
  1143.    CALL FindNextF(ErrCode%)
  1144.    IF ErrCode% THEN PRINT "No more matching files"
  1145.  
  1146. Name: FOpen
  1147.  
  1148. Type: Disk / DOS
  1149.  
  1150. Description:
  1151.    Opens an existing file for use with ADVBAS routines.  If you want to
  1152.    create a new file, use the FCreate routine instead.
  1153.  
  1154.    You must specify the read/write mode:
  1155.       0   open for reading
  1156.       1   open for writing
  1157.       2   open for reading and writing
  1158.  
  1159.    You must also specify the sharing mode:
  1160.       0   no file sharing is allowed
  1161.       1   no other program may access the file while we're using it
  1162.       2   no other program may write to the file while we're using it
  1163.       3   no other program may read from the file while we're using it
  1164.       4   other programs may read/write the file while we're using it
  1165.  
  1166.    Sharing modes are important for multitasking and networking.  You are
  1167.    advised to use "Sharing% = 2" if you are only reading from a file, so that
  1168.    you don't tie it up unnecessarily.  The sharing mode will be ignored on
  1169.    DOS versions prior to 3.0.
  1170.  
  1171.    If there is no error, a "handle" will be returned with which you can
  1172.    access the file using other ADVBAS routines.
  1173.  
  1174. Related functions:
  1175.    FClose, FCreate, FRead, FSetEnd, FSetRec, FWrite
  1176.  
  1177. Example:
  1178.    ReadWrite% = 0     ' open for reading
  1179.    Sharing% = 2       ' allow other programs to read file at the same time
  1180.    CALL FOpen(File$ + CHR$(0), ReadWrite%, Sharing%, Handle%, ErrCode%)
  1181.    IF ErrCode% THEN PRINT "Error: unable to open file "; File$
  1182.  
  1183. Name: FRead
  1184.  
  1185. Type: Disk / DOS
  1186.  
  1187. Description:
  1188.    Reads information from a file opened by FOpen or FCreate.  You must
  1189.    specify the file handle which was returned to you by the open routine.
  1190.    You must also provide a buffer to hold the information that is read.  This
  1191.    buffer may be provided by an array, fixed-length string, or TYPEd
  1192.    variable.  The file pointer will be updated appropriately after the read.
  1193.  
  1194.    A nonzero error code is returned if something went wrong.  An error code
  1195.    of negative one indicates that the end of the file was reached before all
  1196.    of the specified bytes could be read.  In that case, BytesRead% will tell
  1197.    you how many bytes were actually read.
  1198.  
  1199. Related routines:
  1200.    FClose, FCreate, FOpen, FSetEnd, FSetRec, FWrite
  1201.  
  1202. Example:
  1203.    DIM Buffer AS STRING*512     ' 512-byte fixed-length string buffer
  1204.    ' somewhere in here you would use FOpen or FCreate to open a file
  1205.    Bytes% = 512                 ' read 512 bytes
  1206.    DSeg% = VARSEG(Buffer)
  1207.    DOfs% = VARPTR(Buffer)
  1208.    CALL FRead(Handle%, DSeg%, Dofs%, Bytes%, BytesRead%, ErrCode%)
  1209.    IF ErrCode% THEN PRINT "Error reading from file"
  1210.  
  1211.  
  1212.  
  1213.  
  1214. Name: FSetEnd
  1215.  
  1216. Type: Disk / DOS
  1217.  
  1218. Description:
  1219.    Sets the file pointer (of a file opened by FOpen or FCreate) to the end of
  1220.    the file.  This allows you to append information to the end of a file.
  1221.  
  1222. Related routines:
  1223.    FClose, FCreate, FOpen, FRead, FSetRec, FWrite
  1224.  
  1225. Example:
  1226.    CALL FSetEnd(Handle%)
  1227.  
  1228. Name: FSetRec
  1229.  
  1230. Type: Disk / DOS
  1231.  
  1232. Description:
  1233.    Sets the file pointer (of a file opened by FOpen or FCreate) to a specific
  1234.    record in the file.  The next read from (or write to) the file will begin
  1235.    at that point.
  1236.  
  1237. Related routines:
  1238.    FClose, FCreate, FOpen, FRead, FSetEnd, FWrite
  1239.  
  1240. Example:
  1241.    RecSize% = 128         ' 128 bytes per record
  1242.    RecNum% = 34           ' record number 34
  1243.    CALL FSetRec(Handle%, RecSize%, RecNum%)
  1244.  
  1245.  
  1246.  
  1247.  
  1248. Name: FWrite
  1249.  
  1250. Type: Disk / DOS
  1251.  
  1252. Description:
  1253.    Writes information to a file opened by FOpen or FCreate.  You must specify
  1254.    the file handle which was returned to you by the open routine.  You must
  1255.    also provide the location of the buffer that holds the information to be
  1256.    written.  This buffer may be an array, fixed-length string, or TYPEd
  1257.    variable.  The file pointer will be updated appropriately after the write.
  1258.  
  1259.    A nonzero error code is returned if something went wrong.  In that case,
  1260.    BytesWritten% will tell you the how many bytes were actually written.
  1261.  
  1262. Related routines:
  1263.    FClose, FCreate, FOpen, FRead, FSetEnd, FSetRec
  1264.  
  1265. Example:
  1266.    DIM Buffer AS STRING*512     ' 512-byte fixed-length string buffer
  1267.    ' somewhere in here you would use FOpen or FCreate to open a file
  1268.    Bytes% = 512                 ' write 512 bytes
  1269.    DSeg% = VARSEG(Buffer)
  1270.    DOfs% = VARPTR(Buffer)
  1271.    CALL FWrite(Handle%, DSeg%, Dofs%, Bytes%, BytesWritten%, ErrCode%)
  1272.    IF ErrCode% THEN PRINT "Error writing to file"
  1273.  
  1274. Name: GetAttrF
  1275.  
  1276. Type: Disk / DOS
  1277.  
  1278. Description:
  1279.    Returns the attribute of a file matched by FindFirstF or FindNextF.  The
  1280.    attribute may be any combination of the following:
  1281.       0    normal file
  1282.       2    hidden file
  1283.       4    system file
  1284.      16    subdirectory
  1285.      32    (archive bit)
  1286.  
  1287.    The archive bit is used by some backup programs to detect whether a file
  1288.    has been backed up or not.  Generally you should simply ignore it.
  1289.    Decoding the attribute can be done with the AND operator (see example).
  1290.  
  1291. Example:
  1292.    CALL GetAttrF(Attr%)
  1293.    IF (Attr% AND 31) = 0 THEN
  1294.       PRINT "Normal file"
  1295.    ELSE
  1296.       IF Attr% AND 2 THEN PRINT "Hidden file"
  1297.       IF Attr% AND 4 THEN PRINT "System file"
  1298.       IF Attr% AND 16 THEN PRINT "Subdirectory"
  1299.    END IF
  1300.  
  1301.  
  1302.  
  1303.  
  1304. Name: GetCRT
  1305.  
  1306. Type: Video / BIOS
  1307.  
  1308. Description:
  1309.    Tells you what kind of display is being used.  The returned value will be
  1310.    zero if monochrome or nonzero if color.  Note that this routine cannot
  1311.    detect if a monochrome monitor is being used with a CGA card, in which
  1312.    case a false "color" will be returned.
  1313.  
  1314. Example:
  1315.    CALL GetCRT(ColorDisplay%)
  1316.    IF ColorDisplay% THEN
  1317.       PRINT "A color display is being used"
  1318.    ELSE
  1319.       PRINT "A monochrome display is being used"
  1320.    END IF
  1321.  
  1322.  
  1323.  
  1324.  
  1325. Name: GetExtM
  1326.  
  1327. Type: Miscellaneous / AT BIOS
  1328.  
  1329. Description:
  1330.    Gets the amount of extended memory available.  This routine requires the
  1331.    AT BIOS (only ATs can have extended memory) and should not be used with
  1332.    PC or XT computers.
  1333.  
  1334. Example:
  1335.    CALL GetExtM(KBytes%)
  1336.    PRINT KBytes%; "kilobytes of extended memory"
  1337.  
  1338. Name: GetKbd
  1339.  
  1340. Type: Input / CLONE
  1341.  
  1342. Description:
  1343.    Gets the state of the keyboard toggles.  The associated variable will be
  1344.    nonzero if the toggle is on or zero if it is off.
  1345.  
  1346. Example:
  1347.    CALL GetKbd(Insert%, CapsLock%, NumLock%, ScrollLock%)
  1348.    IF Insert% THEN PRINT "Insert mode is on"
  1349.    IF CapsLock% THEN PRINT "Caps Lock is on"
  1350.    IF NumLock% THEN PRINT "The keypad is in numeric mode"
  1351.    IF ScrollLock% THEN PRINT "Scroll Lock is on"
  1352.  
  1353.  
  1354.  
  1355.  
  1356. Name: GetDateF
  1357.  
  1358. Type: Disk / DOS
  1359.  
  1360. Description:
  1361.    Gets the date of a file matched by FindFirstF or FindNextF.
  1362.  
  1363. Related routines:
  1364.    FindFirstF, FindNextF, GetAttrF, GetNameF, GetSizeF, GetTimeF
  1365.  
  1366. Example:
  1367.    CALL GetDateF(Mnth%, Day%, Year%)
  1368.    ' The month variable isn't spelled "Month" because there's already
  1369.    ' a routine by that name and QB would get upset.
  1370.  
  1371.  
  1372.  
  1373.  
  1374. Name: GetDOSv
  1375.  
  1376. Type: Miscellaneous / DOS
  1377.  
  1378. Description:
  1379.    Gets the DOS version.  The major part of the version number is returned in
  1380.    the first parameter, the minor part in the second.  DOS 2.11, for
  1381.    instance, would return "MajVer% = 2" and "MinVer% = 11".
  1382.  
  1383. Example:
  1384.    CALL GetDOSv(MajVer%, MinVer%)
  1385.  
  1386. Name: GetDrv
  1387.  
  1388. Type: Disk / DOS
  1389.  
  1390. Description:
  1391.    Gets the default drive.  The result string must be initialized to at least
  1392.    one character.
  1393.  
  1394. Example:
  1395.    Drive$ = "x:"
  1396.    CALL GetDrv(Drive$)
  1397.  
  1398.  
  1399.  
  1400.  
  1401. Name: GetFAttr
  1402.  
  1403. Type: Disk / DOS
  1404.  
  1405. Description:
  1406.    Gets the attribute of a file.  This attribute may be any combination of
  1407.    the following:
  1408.  
  1409.       0    normal file
  1410.       2    hidden file
  1411.       4    system file
  1412.      16    subdirectory
  1413.      32    (archive bit)
  1414.  
  1415.    The archive bit is used by some backup programs to detect whether a file
  1416.    has been backed up or not.  Generally you should simply ignore it.
  1417.    Decoding the attribute can be done with the AND operator (see example).
  1418.  
  1419. Example:
  1420.    CALL GetFAttr(File$ + CHR$(0), Attr%)
  1421.    IF (Attr% AND 31) = 0 THEN
  1422.       PRINT "Normal file"
  1423.    ELSE
  1424.       IF Attr% AND 2 THEN PRINT "Hidden file"
  1425.       IF Attr% AND 4 THEN PRINT "System file"
  1426.       IF Attr% AND 16 THEN PRINT "Subdirectory"
  1427.    END IF
  1428.  
  1429.  
  1430.  
  1431.  
  1432. Name: GetFDate
  1433.  
  1434. Type: Disk / DOS
  1435.  
  1436. Description:
  1437.    Gets the date of a file.  If there is no such file, the month variable
  1438.    will be set to negative one.
  1439.  
  1440. Example:
  1441.    CALL GetFDate(File$ + CHR$(0), Mnth%, Day%, Year%)
  1442.    ' The month variable isn't spelled "Month" because there's already
  1443.    ' a routine by that name and QB would get upset.
  1444.  
  1445. Name: GetFTime
  1446.  
  1447. Type: Disk / DOS
  1448.  
  1449. Description:
  1450.    Gets the time of a file.  The hour is in 24-hour format (0-23) and will be
  1451.    set to negative one if there is no such file.  The seconds are rounded to
  1452.    the next lower even number, due to the way DOS stores the time.
  1453.  
  1454. Example:
  1455.    CALL GetFTime(File$ + CHR$(0), Hour%, Minute%, Second%)
  1456.  
  1457.  
  1458.  
  1459.  
  1460. Name: GetKey
  1461.  
  1462. Type: Keyboard / BIOS
  1463.  
  1464. Description:
  1465.    Waits until one of a specified list of keys is pressed and returns that
  1466.    key in uppercase.  If the key list is null, the first key pressed will be
  1467.    returned.  You must initialize the return string to at least one
  1468.    character.
  1469.  
  1470. Example:
  1471.    PRINT "Would you like to try again (Y/N)? ";
  1472.    GoodKey$ = "YN"
  1473.    Ky$ = "x"
  1474.    CALL GetKey(GoodKey$, Ky$)
  1475.  
  1476.  
  1477.  
  1478.  
  1479. Name: GetLIMm
  1480.  
  1481. Type: Miscellaneous / BIOS
  1482.  
  1483. Description:
  1484.    Gets the status of expanded memory.  The number of total pages and number
  1485.    of free pages are returned (a page is 16 Kbytes).  Zeros will be returned
  1486.    if no expanded memory is installed.
  1487.  
  1488. Example:
  1489.    CALL GetLIMm(TotalPages%, FreePages%)
  1490.    IF TotalPages% THEN
  1491.       PRINT "Expanded memory is installed."
  1492.       PRINT "  Total 16K pages:"; TotalPages%
  1493.       PRINT "  Free  16K pages:"; FreePages%
  1494.    ELSE
  1495.       PRINT "No expanded memory is available."
  1496.    END IF
  1497.  
  1498. Name: GetLine
  1499.  
  1500. Type: Video / ANY
  1501.  
  1502. Description:
  1503.    Gets a specified line (row) from a saved screen into a string.  The screen
  1504.    may have been saved with one of the ScrSave routines, or with GetScreen
  1505.    provided that full 80-column rows were saved.  The result will have the
  1506.    colors and trailing spaces removed, so it will be a printable text string.
  1507.  
  1508. Example:
  1509.    DIM Buffer AS STRING * 4000       ' 4,000 bytes for one saved screen
  1510.    DSeg% = VARSEG(Buffer)
  1511.    DOfs% = VARPTR(Buffer)
  1512.    CALL ScrSave(DSeg%, DOfs%)
  1513.    OPEN "SCREEN.TXT" FOR OUTPUT AS #1
  1514.    RowText$ = SPACE$(80)
  1515.    FOR Row% = 1 TO 25
  1516.       CALL GetLine(VARSEG(Buffer), VARPTR(Buffer), Row%, RowText$, RLen%)
  1517.       PRINT #1, LEFT$(RowText$, RLen%)
  1518.    NEXT
  1519.    CLOSE #1
  1520.    ' saves the screen to the text file SCREEN.TXT
  1521.  
  1522.  
  1523.  
  1524.  
  1525. Name: GetNameF
  1526.  
  1527. Type: Disk / DOS
  1528.  
  1529. Description:
  1530.    Gets the name of a file matched by FindFirstF or FindNextF.  The return
  1531.    string must be initialized to at least 12 characters.  The file name will
  1532.    not include a drive or subdirectory specification.
  1533.  
  1534. Related routines:
  1535.    FindFirstF, FindNextF, GetAttrF, GetDateF, GetSizeF, GetTimeF
  1536.  
  1537. Example:
  1538.    FileName$ = SPACE$(12)
  1539.    CALL GetNameF(FileName$, FLen%)
  1540.    FileName$ = LEFT$(FileName$, FLen%)
  1541.  
  1542. Name: GetScreen
  1543.  
  1544. Type: Video / CLONE
  1545.  
  1546. Description:
  1547.    Saves any part of any display page.  You specify the upper left corner and
  1548.    lower right corner of the area to save, the display page to save, a
  1549.    buffer, and the screen mode.  The display page should be zero for MDAs or
  1550.    if you are not using paging.  The screen mode should be zero for old CGA
  1551.    displays that have problems with "snow".  Otherwise, make it nonzero for
  1552.    the best speed.
  1553.  
  1554.    To calculate the necessary buffer size, use the following:
  1555.       Bytes% = (BottomRow% - TopRow% + 1) * (RightCol% - LeftCol% + 1) * 2
  1556.  
  1557. Example:
  1558.    DIM Buffer AS STRING * 4000     ' enough room for a full 80x25 screen
  1559.    ' presumeably your code goes here
  1560.    TopRow% = 1             ' upper left corner
  1561.    LeftCol% = 1
  1562.    BottomRow% = 12         ' lower right corner
  1563.    RightCol% = 80
  1564.    Page% = 0               ' display page zero
  1565.    ScrMode% = -1           ' no snow suppression
  1566.    DSeg% = VARSEG(Buffer)
  1567.    DOfs% = VARPTR(Buffer)
  1568.    CALL GetScreen(DSeg%, DOfs%, TopRow%, LeftCol%, BottomRow%, RightCol%,
  1569.                   Page%, ScrMode%)
  1570.    ' The CALL should actually be on a single line.  It's split up just so
  1571.    ' it'll fit in 80 columns.  This example saves the top half of the screen.
  1572.  
  1573.  
  1574.  
  1575.  
  1576. Name: GetSizeF
  1577.  
  1578. Type: Disk / DOS
  1579.  
  1580. Description:
  1581.    Gets the size of a file matched by FindFirstF or FindNextF.  You must
  1582.    calculate the actual size from the two integers returned, since the size
  1583.    can be larger than will fit into a single integer.
  1584.  
  1585. Example:
  1586.    CALL GetSizeF(SizeLow%, SizeHigh%)
  1587.    FileSize& = (SizeHigh% - (SizeLow% < 0)) * 65536& + CLNG(SizeLow%)
  1588.  
  1589. Name: GetSub
  1590.  
  1591. Type: Disk / DOS
  1592.  
  1593. Description:
  1594.    Gets the default subdirectory on the current drive.  The returned string
  1595.    must be initialized to at least 64 characters.  It will not be started by
  1596.    a backslash, so you should add one if you want it.
  1597.  
  1598. Example:
  1599.    SubDir$ = SPACE$(64)
  1600.    CALL GetSub(SubDir$, SLen%)
  1601.    SubDir$ = "\" + LEFT$(SubDir$, SLen%)
  1602.  
  1603.  
  1604.  
  1605.  
  1606. Name: GetTimeF
  1607.  
  1608. Type: Disk / DOS
  1609.  
  1610. Description:
  1611.    Gets the time of a file matched by FindFirstF or FindNextF.  The hour is
  1612.    returned in 24-hour (0-23) format.
  1613.  
  1614. Related routines:
  1615.    FindFirstF, FindNextF, GetAttrF, GetDateF, GetNameF, GetSizeF
  1616.  
  1617. Example:
  1618.    CALL GetTimeF(Hour%, Minute%, Second%)
  1619.  
  1620.  
  1621.  
  1622.  
  1623. Name: InsChr
  1624.  
  1625. Type: Video / CLONE
  1626.  
  1627. Description:
  1628.    Inserts a space at the specified screen position.  The character
  1629.    previously at that position and all characters to the right of it on the
  1630.    same row will be shifted right to make room.  This works only in text mode
  1631.    (SCREEN 0) on display page zero.
  1632.  
  1633. Example:
  1634.    Row% = CSRLIN
  1635.    Col% = POS(0)
  1636.    CALL InsChr(Row%, Col%)      ' insert a space at the cursor
  1637.  
  1638. Name: Int2Date
  1639.  
  1640. Type: Miscellaneous / ANY
  1641.  
  1642. Description:
  1643.    Uncompresses a date that was compressed by Date2Int.  The year will be
  1644.    returned in four-digit format (1900-2026).
  1645.  
  1646. Example:
  1647.    CALL Int2Date(Mnth%, Day%, Year%, SqueezedDate%)
  1648.    ' we use Mnth% instead of Month% since there is a Month routine in ADVBAS
  1649.    ' and QuickBASIC doesn't like variables to share names with routines
  1650.  
  1651.  
  1652.  
  1653.  
  1654. Name: Int2Time
  1655.  
  1656. Type: Miscellaneous / ANY
  1657.  
  1658. Description:
  1659.    Uncompresses a time that was compressed by Time2Int.  The seconds will be
  1660.    an even value (rounded down) due to the storage format used.
  1661.  
  1662. Example:
  1663.    CALL Int2Time(Hour%, Minute%, Second%, SqueezedTime%)
  1664.  
  1665.  
  1666.  
  1667.  
  1668. Name: KeyPress
  1669.  
  1670. Type: Keyboard / BIOS
  1671.  
  1672. Description:
  1673.    Tells whether a key is waiting in the keyboard buffer.  The return value
  1674.    is nonzero if a key is ready to be processed.
  1675.  
  1676. Example:
  1677.    DO
  1678.       CALL KeyPress(KeyHit%)
  1679.    LOOP UNTIL KeyHit%
  1680.    Ky$ = INKEY$
  1681.  
  1682.  
  1683.  
  1684.  
  1685. Name: LoCase
  1686.  
  1687. Type: String / ANY
  1688.  
  1689. Description:
  1690.    Converts the letters in a string to lowercase.  This is much faster than
  1691.    the LCASE$ function provided by QuickBASIC.
  1692.  
  1693. Example:
  1694.    CALL LoCase(St$)
  1695.  
  1696. Name: LRotate
  1697.  
  1698. Type: String / ANY
  1699.  
  1700. Description:
  1701.    Rotates the characters in a string left.  All characters are moved left
  1702.    once, with the original leftmost character ending up on the right end of
  1703.    the resulting string.  This routine is useful for rotating queues and
  1704.    character-graphics animation or marquee displays.
  1705.  
  1706. Example:
  1707.    St$ = "12345"
  1708.    CALL LRotate(St$)       ' the result will be "23451"
  1709.  
  1710.  
  1711.  
  1712.  
  1713. Name: MakeSub
  1714.  
  1715. Type: Disk / DOS
  1716.  
  1717. Description:
  1718.    Creates a subdirectory.  A nonzero error code will be returned if it isn't
  1719.    possible to create the subdirectory.
  1720.  
  1721. Example:
  1722.    CALL MakeSub(SubDir$ + CHR$(0), ErrCode%)
  1723.    IF ErrCode% THEN
  1724.       PRINT "Error: unable to create subdirectory "; SubDir$
  1725.    END IF
  1726.  
  1727. Name: MakeWindow
  1728.  
  1729. Type: Video / CLONE
  1730.  
  1731. Description:
  1732.    Displays a pop-up window.  You may choose from a variety of frame types
  1733.    and window types.  A window label may optionally be displayed as well.
  1734.  
  1735.    The window frame is drawn -outside- of the window you've specified, so be
  1736.    sure to allow extra room for the frame.  Normal windows require one space
  1737.    around on each side.  Shadowed windows require an extra two columns on the
  1738.    left and bottom sides.
  1739.  
  1740.    Four types of windows may be displayed:
  1741.       0    normal              the window pops onto the screen
  1742.       1    growing             the window "explodes" onto the screen
  1743.       2    shadowed            the window is "shadowed" for a 3-D effect
  1744.       3    growing/shadowed    the window is both growing and shadowed
  1745.  
  1746.    Five types of frames may be chosen:
  1747.       0    none      spaces
  1748.       1    single    single lines
  1749.       2    double    double lines
  1750.       3    2v, 1h    double vertical lines and single horizontal lines
  1751.       4    1v, 2h    single vertical lines and double vertical lines
  1752.  
  1753. Example:
  1754.    TopRow% = 5                ' top left corner
  1755.    LeftCol% = 5
  1756.    BottomRow% = 20            ' bottom left corner
  1757.    RightCol% = 79
  1758.    Label$ = "Test Window"     ' this would be "" for no label
  1759.    Frame% = 1                 ' frame type (single lines)
  1760.    WindType% = 3              ' window type (growing/shadowed)
  1761.    Fore% = 7                  ' foreground color (white)
  1762.    Back% = 0                  ' background color (black)
  1763.    Page% = 0                  ' display page
  1764.    CALL MakeWindow(LeftCol%, TopRow%, RightCol%, BottomRow%, Label$,
  1765.                    Frame%, WindType%, Fore%, Back%, Page%)
  1766.    ' The above CALL should be on one line in your program and is only
  1767.    ' divided here so it'll fit on your display or printer.
  1768.    ' NOTE that the coordinates are specified in Column, Row format rather
  1769.    ' than the more ordinary Row, Column format (sorry about that!)
  1770.  
  1771. Name: MDelChr
  1772.  
  1773. Type: Video / BIOS
  1774.  
  1775. Description:
  1776.    Deletes the character at the current cursor position.  The delete
  1777.    operation affects only the area of the screen defined by MWindow.
  1778.  
  1779. Example:
  1780.    CALL MDelChr
  1781.  
  1782.  
  1783.  
  1784.  
  1785. Name: MInsChr
  1786.  
  1787. Type: Video / BIOS
  1788.  
  1789. Description:
  1790.    Inserts a space at the current cursor position.  The insert operation
  1791.    affects only the area of the screen defined by MWindow.
  1792.  
  1793. Example:
  1794.    CALL MInsChr
  1795.  
  1796.  
  1797.  
  1798.  
  1799. Name: MmButton
  1800.  
  1801. Type: Input / BIOS
  1802.  
  1803. Description:
  1804.    Gets the state of the mouse buttons.  If a button is currently being held
  1805.    down, a nonzero value will be returned in the appropriate variable.  See
  1806.    also the MmClick routine.
  1807.  
  1808. Example:
  1809.    CALL MmButton(LeftButton%, RightButton%)
  1810.    IF LeftButton% THEN PRINT "The left button is being pressed."
  1811.    IF RightButton% THEN PRINT "The right button is being pressed."
  1812.  
  1813. Name: MmCheck
  1814.  
  1815. Type: Input / BIOS
  1816.  
  1817. Description:
  1818.    Tells whether a mouse is installed.  If not, zero is returned.  If so, the
  1819.    number of buttons that the mouse has is installed.
  1820.  
  1821. Example:
  1822.    CALL MmCheck(Mouse%)
  1823.    IF Mouse% THEN
  1824.       PRINT "A mouse with"; Mouse%; "buttons is present."
  1825.    ELSE
  1826.       PRINT "No mouse is available."
  1827.    END IF
  1828.  
  1829.  
  1830.  
  1831.  
  1832. Name: MmClick
  1833.  
  1834. Type: Input / BIOS
  1835.  
  1836. Description:
  1837.    Tells which mouse buttons have been pressed since you last used this
  1838.    routine.  The number of times each button has been pressed is returned.
  1839.    See also the MmButton routine.
  1840.  
  1841. Example:
  1842.    CALL MmClick(LeftButton%, RightButton%)
  1843.    IF LeftButton% THEN PRINT "The left mouse button was pressed."
  1844.    IF RightButton% THEN PRINT "The right mouse button was pressed."
  1845.  
  1846.  
  1847.  
  1848.  
  1849. Name: MmCursorOn
  1850.  
  1851. Type: Input / BIOS
  1852.  
  1853. Description:
  1854.    Makes the mouse cursor visible.
  1855.  
  1856. Example:
  1857.    CALL MmCursorOn
  1858.  
  1859.  
  1860.  
  1861.  
  1862. Name: MmCursorOff
  1863.  
  1864. Type: Input / BIOS
  1865.  
  1866. Description:
  1867.    Makes the mouse cursor invisible.  It will still be there and will
  1868.    function normally, but it won't be displayed.
  1869.  
  1870. Example:
  1871.    CALL MmCursorOff
  1872.  
  1873. Name: MmGetLoc
  1874.  
  1875. Type: Input / BIOS
  1876.  
  1877. Description:
  1878.    Gets the location of the mouse cursor.  This is returned as a value based
  1879.    on a 640x200 graphics screen.  If you are in an 80x25 text mode, divide
  1880.    both the columns and the rows by eight to compensate, and add one to each
  1881.    since text-mode coordinates start at (1,1).  If you're in the 320x200
  1882.    graphics mode, divide the columns by two.  If you're in 640x200 graphics
  1883.    mode, of course, the numbers are fine as-is.
  1884.  
  1885. Example:
  1886.    CALL MmGetLoc(Column%, Row%)
  1887.    Column% = Column% \ 8 + 1     ' convert from 0-639 to 1-80
  1888.    Row% = Row% \ 8 + 1           ' convert from 0-199 to 1-25
  1889.    LOCATE Row%, Column%
  1890.    PRINT "+";
  1891.  
  1892.  
  1893.  
  1894.  
  1895. Name: MmSetLoc
  1896.  
  1897. Type: Input / BIOS
  1898.  
  1899. Description:
  1900.    Sets the location of the mouse cursor.  The same 640x200 format as for
  1901.    MmGetLoc (see) is used.
  1902.  
  1903. Example:
  1904.    Row% = CSRLIN * 8 - 4         ' convert from 1-25 to 0-199
  1905.    Column% = POS(0) * 8 - 4      ' convert from 1-80 to 0-639
  1906.    CALL MmSetLoc(Column%, Row%)
  1907.  
  1908.  
  1909.  
  1910.  
  1911. Name: MmSetRange
  1912.  
  1913. Type: Input / BIOS
  1914.  
  1915. Description:
  1916.    Sets the range for the mouse cursor, which will not be able to move
  1917.    outside the specified rectangle.  The same 640x200 format as for MmGetLoc
  1918.    (see) is used.
  1919.  
  1920. Example:
  1921.    LeftCol% = 40      ' top left corner
  1922.    TopRow% = 10
  1923.    RightCol% = 600    ' bottom right corner
  1924.    BottomRow% = 190
  1925.    CALL MmSetRange(LeftCol%, TopRow%, RightCol%, BottomRow%)
  1926.  
  1927. Name: MLoad
  1928.  
  1929. Type: Disk / DOS
  1930.  
  1931. Description:
  1932.    A fast replacement for the BLOAD statement.  The file is loaded into the
  1933.    area of memory from which it came when BSAVEd.
  1934.  
  1935. Example:
  1936.    File$ = "PICTURE.BAS"
  1937.    CALL MLoad(File$ + CHR$(0))
  1938.  
  1939.  
  1940.  
  1941.  
  1942. Name: Month
  1943.  
  1944. Type: Miscellaneous / ANY
  1945.  
  1946. Description:
  1947.    Gets the name of the month, given the month number.  You must initialize
  1948.    the return string to at least nine characters.
  1949.  
  1950. Example:
  1951.    FOR MonthNum% = 1 to 12
  1952.       Mnth$ = SPACE$(9)
  1953.       CALL Month(Mnth$, MLen%, MonthNum%)
  1954.       Mnth$ = LEFT$(Mnth$, MLen%)
  1955.       PRINT "Month"; MonthNum%; "is "; Mnth%
  1956.    NEXT
  1957.    ' This prints the name of each month.
  1958.    ' The variable MONTH$ isn't used in order to avoid conflicts with
  1959.    ' the routine named MONTH (QuickBASIC gets picky there).
  1960.  
  1961.  
  1962.  
  1963.  
  1964. Name: MPrintC
  1965.  
  1966. Type: Video / BIOS
  1967.  
  1968. Description:
  1969.    Sends a character to the display using (mostly) DOS output.  This allows
  1970.    use of ANSI.SYS and supports output redirection.  The output will remain
  1971.    in the window defined by MWindow.  The new cursor position is returned so
  1972.    that you can tell QB about it using LOCATE.  Note that the coordinates are
  1973.    returned in reverse order!
  1974.  
  1975. Example:
  1976.    CALL MPrintC(Ch$, Column%, Row%)
  1977.    LOCATE Row%, Column%
  1978.  
  1979. Name: MPrint
  1980.  
  1981. Type: Video / BIOS
  1982.  
  1983. Description:
  1984.    Sends a string to the display using (mostly) DOS output.  This allows the
  1985.    use of ANSI.SYS and supports output redirection.  The output will remain
  1986.    in the window defined by MWindow.  The new cursor position is returned so
  1987.    that you can tell QB about it using LOCATE.  Note that the coordinates are
  1988.    returned in reverse order!
  1989.  
  1990. Example:
  1991.    CALL MPrint(St$, Column%, Row%)
  1992.    LOCATE Row%, Column%
  1993.  
  1994.  
  1995.  
  1996.  
  1997. Name: MultiAND
  1998.  
  1999. Type: String / ANY
  2000.  
  2001. Description:
  2002.    Performs an arithmetic AND operation on each character in a string.  See
  2003.    your BASIC manual for a discussion of the AND operator.
  2004.  
  2005. Example:
  2006.    CALL MultiAND(St$, BitMask%)
  2007.  
  2008.  
  2009.  
  2010.  
  2011. Name: MultiOR
  2012.  
  2013. Type: String / ANY
  2014.  
  2015. Description:
  2016.    Performs an arithmetic OR operation on each character in a string.  See
  2017.    your BASIC manual for a discussion of the OR operator.
  2018.  
  2019. Example:
  2020.    CALL MultiOR(St$, SetBits%)
  2021.  
  2022.  
  2023.  
  2024.  
  2025. Name: MultiXOR
  2026.  
  2027. Type: String / ANY
  2028.  
  2029. Description:
  2030.    Performs an arithmetic XOR operation on each character in a string.  See
  2031.    your BASIC manual for a discussion of the XOR operator.  Note that this
  2032.    will also function as a "MultiNOT" if you use BitMask% = 255.
  2033.  
  2034. Example:
  2035.    CALL MultiXOR(St$, BitMask%)
  2036.  
  2037. Name: MWindow
  2038.  
  2039. Type: Video / BIOS
  2040.  
  2041. Description:
  2042.    Defines the screen area for the MPrint, MPrintC, MInsChr and MDelChr
  2043.    routines.  The output from those functions will be confined to the
  2044.    specified window.  After using MWindow, you should make sure that the
  2045.    cursor is inside the defined area with LOCATE.  Do not define a window of
  2046.    less than two rows.
  2047.  
  2048. Example:
  2049.    CALL MWindow(LeftColumn%, TopRow%, RightColumn%, BottomRow%)
  2050.    LOCATE TopRow%, LeftColumn%
  2051.  
  2052.  
  2053.  
  2054.  
  2055. Name: PrintScreen
  2056.  
  2057. Type: Miscellaneous / BIOS
  2058.  
  2059. Description:
  2060.    Prints a copy of the screen on the first printer device.  This is just
  2061.    like using Shift-PrtSc (or Print Screen) from your keyboard.  It can also
  2062.    display CGA graphics if you install the GRAPHICS.COM program that came
  2063.    with your copy of MS-DOS.
  2064.  
  2065. Example:
  2066.    CALL PrintScreen
  2067.  
  2068.  
  2069.  
  2070.  
  2071. Name: PutScreen
  2072.  
  2073. Type: Video / CLONE
  2074.  
  2075. Description:
  2076.    Restores a saved screen area to any part of any display page.  You specify
  2077.    the upper left corner and lower right corner of the area to which to
  2078.    restore, the display page to which to restore, the saved screen buffer,
  2079.    and the screen mode.  The display page should be zero for MDAs or if you
  2080.    are not using paging.  The screen mode should be zero for old CGA displays
  2081.    that have problems with "snow".  Otherwise, make it nonzero for the best
  2082.    speed.
  2083.  
  2084. Example:
  2085.    ' presumeably you used GetScreen before this, saving it to Buffer...
  2086.    TopRow% = 1             ' upper left corner
  2087.    LeftCol% = 1
  2088.    BottomRow% = 12         ' lower right corner
  2089.    RightCol% = 80
  2090.    Page% = 0               ' display page zero
  2091.    ScrMode% = -1           ' no snow suppression
  2092.    DSeg% = VARSEG(Buffer)
  2093.    DOfs% = VARPTR(Buffer)
  2094.    CALL PutScreen(DSeg%, DOfs%, TopRow%, LeftCol%, BottomRow%, RightCol%,
  2095.                   Page%, ScrMode%)
  2096.    ' The CALL should actually be on a single line.  It's split up just so
  2097.    ' it'll fit in 80 columns.  This example saves the top half of the screen.
  2098.  
  2099. Name: QPrint
  2100.  
  2101. Type: Video / CLONE
  2102.  
  2103. Description:
  2104.    Displays a string directly to the screen, very quickly, using the colors
  2105.    that are already on the screen.  Control characters are not translated and
  2106.    will always show up as graphics characters.  Display page zero is used.
  2107.    This routine does not update the cursor position, and must be used in text
  2108.    modes (SCREEN 0).
  2109.  
  2110. Related routines:
  2111.    XqPrint
  2112.  
  2113. Example:
  2114.    St$ = "This is a test of fast screen printing"
  2115.    Row% = 10
  2116.    Col%=20
  2117.    CALL QPrint(St$, Row%, Col%)
  2118.  
  2119.  
  2120.  
  2121.  
  2122. Name: ReadBitF
  2123.  
  2124. Type: Miscellaneous / ANY
  2125.  
  2126. Description:
  2127.    Provides support for arrays of arbitrary bit length (1-8 bits).  The index
  2128.    may range 0-65,535 (use a long integer for indices of over 32,767).
  2129.  
  2130. Example:
  2131.    DSeg% = VARSEG(ArrayBuffer)
  2132.    DOfs% = VARPTR(ArrayBuffer)
  2133.    CALL ReadBitF(DSeg%, DOfs$, Indx&, BitLength%, Result%)
  2134.  
  2135.  
  2136.  
  2137.  
  2138. Name: ReColor
  2139.  
  2140. Type: Video / CLONE
  2141.  
  2142. Description:
  2143.    Converts one color to another, across the entire screen.  Text modes
  2144.    (SCREEN 0) are required.  Define the old and new colors using the CalcAttr
  2145.    routine.
  2146.  
  2147. Example:
  2148.    CALL ReColor(OldColor%, NewColor%)
  2149.  
  2150.  
  2151.  
  2152.  
  2153. Name: ResetPoint
  2154.  
  2155. Type: Video / BIOS
  2156.  
  2157. Description:
  2158.    Resets a point.  This provides support for 80x50 graphics in text mode
  2159.    (SCREEN 0).
  2160.  
  2161. Related routines:
  2162.    SetPoint, TestPoint
  2163.  
  2164. Example:
  2165.    CALL ResetPoint(Column%, Row%)
  2166.  
  2167. Name: Reverse
  2168.  
  2169. Type: String / ANY
  2170.  
  2171. Description:
  2172.    Reverses the order of the characters in a string.  This can be used with
  2173.    INSTR to find the last occurrence of a substring within a string, for
  2174.    instance.
  2175.  
  2176. Example:
  2177.    St$ = "This is a test"
  2178.    CALL Reverse(St$)
  2179.    PRINT St$
  2180.  
  2181.  
  2182.  
  2183.  
  2184. Name: RRotate
  2185.  
  2186. Type: String / ANY
  2187.  
  2188. Description:
  2189.    Rotates the characters in a string right.  All characters are moved right
  2190.    once, with the original rightmost character ending up on the left end of
  2191.    the resulting string.  This routine is useful for rotating queues and
  2192.    character-graphics animation or marquee displays.
  2193.  
  2194. Example:
  2195.    St$ = "12345"
  2196.    CALL RRotate(St$)       ' the result will be "51234"
  2197.  
  2198.  
  2199.  
  2200.  
  2201. Name: Scroll
  2202.  
  2203. Type: Video / BIOS
  2204.  
  2205. Description:
  2206.    Scrolls any selected part of the screen up by a specified number of lines.
  2207.    If you tell it to scroll zero lines, the specified area will be cleared.
  2208.  
  2209. Example:
  2210.    TopRow% = 1
  2211.    LeftCol% = 1
  2212.    BottomRow% = 25
  2213.    RightCol% = 80
  2214.    Times% = 2
  2215.    CALL Scroll(LeftCol%, TopRow%, RightCol%, BottomRow%, Times%)
  2216.    ' scrolls the entire screen up two lines
  2217.  
  2218. Name: ScrRest
  2219.  
  2220. Type: Video / CLONE
  2221.  
  2222. Description:
  2223.    Restores a saved screen to the display.  Requires text mode (SCREEN 0) and
  2224.    uses display page zero.
  2225.  
  2226. Example:
  2227.    ' presumeably you used ScrSave before this, saving it to Buffer...
  2228.    DSeg% = VARSEG(Buffer)
  2229.    DOfs% = VARPTR(Buffer)
  2230.    CALL ScrRest(Dseg%, DOfs%)
  2231.  
  2232.  
  2233.  
  2234.  
  2235. Name: ScrSave
  2236.  
  2237. Type: Video / CLONE
  2238.  
  2239. Description:
  2240.    Saves the screen to a buffer.  Requires text mode (SCREEN 0) and uses
  2241.    display page zero.  The buffer must hold at least 4,000 bytes.
  2242.  
  2243. Example:
  2244.    REDIM Buffer AS STRING * 4000
  2245.    DSeg% = VARSEG(Buffer)
  2246.    DOfs% = VARPTR(Buffer)
  2247.    CALL ScrSave(DSeg%, DOfs%)
  2248.  
  2249.  
  2250.  
  2251.  
  2252. Name: ScrRestP, ScrRestPD, ScrSaveP, ScrSavePD
  2253.  
  2254. Type: Video / CLONE
  2255.  
  2256. Description:
  2257.    These routines are variations on ScrRest and ScrSave.  All of them allow
  2258.    you to specify a display page (use zero on MDAs).  The ones with the "D"
  2259.    suffix do not provide snow suppression, unlike the other routines, but
  2260.    they are much faster.  Snow suppression is only required on some older
  2261.    CGAs and will not affect other displays.
  2262.  
  2263. Example:
  2264.    ' presumeably you used one of the ScrSave routines before this...
  2265.    Page% = 0
  2266.    DSeg% = VARSEG(Buffer)
  2267.    DOfs% = VARPTR(Buffer)
  2268.    CALL ScrRestPD(Dseg%, DOfs%, Page%)
  2269.  
  2270. Name: SetComm
  2271.  
  2272. Type: Miscellaneous / CLONE
  2273.  
  2274. Description:
  2275.    Sets the parameters for an open communications device.  You don't have to
  2276.    close the device to change the parameters, so you don't have to risk
  2277.    losing your connection.  The baud rate can also be set much higher than
  2278.    BASIC normally allows, although the useful speeds will depend on your
  2279.    particular hardware and program design.
  2280.  
  2281.    The number of bits per second ("baud rate") is specified as follows:
  2282.  
  2283.               Baud       Use                   Baud        Use
  2284.              -----       ---                  ------       ---
  2285.                300        0                    9,600        5
  2286.                600        1                   19,200        6
  2287.              1,200        2                   38,400        7
  2288.              2,400        3                   57,600        8
  2289.              4,800        4
  2290.  
  2291. Example:
  2292.    OPEN "R", 1, "COM1:300,E,7,1,RS,CS,DS"
  2293.    CommPort% = 1          ' may be 1 or 2
  2294.    Baud% = 6              ' see chart above (here, it means 19,200 baud)
  2295.    Parity% = 0            ' use 0 for None, 1 for Odd, 2 for Even
  2296.    WordLength% = 8        ' may be 7 or 8
  2297.    StopBits% = 1          ' may be 1 or 2
  2298.    CALL SetComm(CommPort$, Baud%, Parity%, WordLength%, StopBits%)
  2299.    ' set COM1 to 19200 baud, No parity, 8 bit words, and 1 stop bit.
  2300.  
  2301.  
  2302.  
  2303.  
  2304. Name: SetDrv
  2305.  
  2306. Type: Disk / DOS
  2307.  
  2308. Description:
  2309.    Sets the default drive.
  2310.  
  2311. Example:
  2312.    Drive$ = "C"
  2313.    CALL SetDrv(Drive$)
  2314.  
  2315. Name: SetFAttr
  2316.  
  2317. Type: Disk / DOS
  2318.  
  2319. Description:
  2320.    Sets a file attribute.  Attributes may be as follows:
  2321.       0    normal file or subdirectory
  2322.       2    hidden file or subdirectory
  2323.       4    system file (don't use unless you know what you're doing)
  2324.  
  2325. Example:
  2326.    Attr% = 2
  2327.    CALL SetFAttr(File$ + CHR$(0), Attr%)     ' hide a file
  2328.  
  2329.  
  2330.  
  2331.  
  2332. Name: SetFTD
  2333.  
  2334. Type: Disk / DOS
  2335.  
  2336. Description:
  2337.    Sets the time and date of a file.  The year may be two or four digits.
  2338.    The hour is specified in 24-hour format, with midnight being 24 rather
  2339.    than the usual 0.  The seconds will be rounded down to the closest even
  2340.    number by DOS.  The month will be set to -1 if there was an error.
  2341.  
  2342. Example:
  2343.    CALL SetFTD(File$ + CHR$(0), Mnth%, Day%, Year%, Hour%, Minute%, Second%)
  2344.    IF Mnth% = -1 THEN PRINT "Error: No such file as "; File$
  2345.  
  2346.  
  2347.  
  2348.  
  2349. Name: SetMatI
  2350.  
  2351. Type: Miscellaneous / ANY
  2352.  
  2353. Description:
  2354.    Sets every element of an integer array to a specified value.
  2355.  
  2356. Example:
  2357.    Lo% = LBOUND(Array%)
  2358.    Hi% = UBOUND(Array%)
  2359.    Elements% = Hi% - Lo% + 1
  2360.    Value% = 100
  2361.    DSeg% = VARSEG(Array%(Lo%))
  2362.    DOfs% = VARPTR(Array%(Lo%))
  2363.    CALL SetMatI(DSeg%, DOfs%, Elements%, Value%)
  2364.    ' we just initialized the entire array to 100
  2365.  
  2366. Name: SetKbd
  2367.  
  2368. Type: Input / CLONE
  2369.  
  2370. Description:
  2371.    Sets the state of the keyboard toggles (keys which switch on and off).  If
  2372.    you provide a nonzero value, the state is turned on.  The state is turned
  2373.    off if the value given is zero.  If you change the keyboard state, you
  2374.    should restore the original state before your program exits.
  2375.  
  2376. Related routines:
  2377.    GetKbd
  2378.  
  2379. Example:
  2380.    Insert% = 1       ' turn on insert mode
  2381.    CapsLock% = 0     ' turn off caps lock
  2382.    NumLock% = 0      ' turn off num lock
  2383.    ScrollLock% = 0   ' turn off scroll lock
  2384.    CALL SetKbd(Insert%, CapsLock%, NumLock%, ScrollLock%)
  2385.  
  2386.  
  2387.  
  2388.  
  2389. Name: SetPoint
  2390.  
  2391. Type: Video / BIOS
  2392.  
  2393. Description:
  2394.    Sets a point.  This provides support for 80x50 graphics in text mode
  2395.    (SCREEN 0).
  2396.  
  2397. Related routines:
  2398.    ResetPoint, TestPoint
  2399.  
  2400. Example:
  2401.    Y% = 24
  2402.    FOR X% = 0 TO 79
  2403.       CALL SetPoint(X%, Y%)
  2404.    NEXT X%
  2405.    ' we just drew a horizontal line across the middle of the screen
  2406.  
  2407.  
  2408.  
  2409.  
  2410. Name: SetSub
  2411.  
  2412. Type: Disk / DOS
  2413.  
  2414. Description:
  2415.    Sets the default subdirectory.  A nonzero error code will be returned if
  2416.    the specified subdirectory doesn't exist.
  2417.  
  2418. Example:
  2419.    CALL SetSub(SubDir$ + CHR$(0), ErrCode%)
  2420.    IF ErrCode% THEN PRINT "Error: No such subdirectory as "; SubDir$
  2421.  
  2422. Name: ShiftL
  2423.  
  2424. Type: Miscellaneous / ANY
  2425.  
  2426. Description:
  2427.    This is a SHL operator.  It shifts all the bits in an integer left by a
  2428.    specified number of times.  The vacated bit positions are zeroed.  For
  2429.    non-negative numbers, this is an efficient way to multiply by a power of
  2430.    two.  Each time you shift left, you effectively multiply the previous
  2431.    value by two.
  2432.  
  2433. Example:
  2434.    Value% = 47
  2435.    Count% = 3
  2436.    CALL ShiftL(Value%, Count%)
  2437.    ' the result will be 47 * 2^3, i.e., 376
  2438.  
  2439.  
  2440.  
  2441.  
  2442. Name: ShiftR
  2443.  
  2444. Type: Miscellaneous / ANY
  2445.  
  2446. Description:
  2447.    This is a SHR operator.  It shifts all the bits in an integer right by a
  2448.    specified number of times.  The vacated bit positions are zeroed.  For
  2449.    non-negative numbers, this is an efficient way to divide by a power of
  2450.    two.  Each time you shift left, you effectively divide the previous value
  2451.    by two.
  2452.  
  2453. Example:
  2454.    Value% = 47
  2455.    Count% = 3
  2456.    CALL ShiftR(Value%, Count%)
  2457.    ' the result will be 47 \ 2^3, i.e., 5
  2458.  
  2459. Name: Soundex
  2460.  
  2461. Type: String / ANY
  2462.  
  2463. Description:
  2464.    Calculates the Soundex code for a specified string.  The Soundex code can
  2465.    be used for comparing strings to see if they sound alike.  Matching is
  2466.    somewhat loose, which allows very nicely for regional pronunciation but
  2467.    also may give matches on some unexpected words.
  2468.  
  2469.    The Soundex code is generated by removing all the vowels from a word and
  2470.    then giving similar-sounding letters (like "t" and "d") the same number.
  2471.    You can compare the results with a target Soundex value using ordinary
  2472.    string comparisons.  If the words are not too long, you could store them
  2473.    conveniently by converting them to long integers.  This will allow you to
  2474.    store a Soundex code of up to nine digits (which allows for words longer
  2475.    than nine characters, since vowels are ignored) in only four bytes (which
  2476.    is the amount of space a long integer requires).
  2477.  
  2478. Example:
  2479.    INPUT "Check the spelling of what word"; Word$
  2480.    SoundexCode$ = Word$
  2481.    CALL Soundex(Word$, SoundexCode$, SLen%)
  2482.    SoundexCode$ = LEFT$(SoundexCode$, SLen%)
  2483.    ' Now you would search through your word list for words which have the
  2484.    ' same Soundex code as SoundexCode$ (might check for null code first).
  2485.  
  2486.  
  2487.  
  2488.  
  2489. Name: Strip
  2490.  
  2491. Type: String / ANY
  2492.  
  2493. Description:
  2494.    Removes all occurrences of a specified character from a string.
  2495.  
  2496. Example:
  2497.    St$ = "12 - 2 =   10"
  2498.    Ch$ = " "
  2499.    CALL Strip(St$, Ch$, SLen%)
  2500.    St$ = LEFT$(St$, SLen%)
  2501.    ' the result will be "12-2=10"
  2502.  
  2503. Name: StripBlanks
  2504.  
  2505. Type: String / ANY
  2506.  
  2507. Description:
  2508.    Removes "white space" from either the left side, the right side, or both
  2509.    sides of a string.  White space consists of blanks and control codes.
  2510.    Specify 1 to strip the left side, 2 for the right side, or 3 for both.
  2511.  
  2512.    This routine differs from the QuickBASIC functions LTRIM$ and RTRIM$ in
  2513.    that it removes control codes as well as blanks.  It is also much faster.
  2514.  
  2515. Example:
  2516.    St$ = "    This is a test    "
  2517.    Side% = 3                        ' strip blanks from both sides
  2518.    CALL StripBlanks(St$, Side%, SLen%)
  2519.    St$ = LEFT$(St$, SLen%)
  2520.    ' the result will be "This is a test"
  2521.  
  2522.  
  2523.  
  2524.  
  2525. Name: StripRange
  2526.  
  2527. Type: String / ANY
  2528.  
  2529. Description:
  2530.    Removes all characters within a specified range from a string.
  2531.  
  2532. Example:
  2533.    St$ = "ALL uppercase letters will be G-O-N-E gone"
  2534.    Lo% = ASC("A")
  2535.    Hi% = ASC("Z")
  2536.    CALL StripRange(St$, Lo%, Hi%, SLen%)
  2537.    St$ = LEFT$(St$, SLen%)
  2538.    ' the result will be " uppercase letters will be --- gone"
  2539.  
  2540.  
  2541.  
  2542.  
  2543. Name: SubExist
  2544.  
  2545. Type: Disk / DOS
  2546.  
  2547. Description:
  2548.    Sees if a specified subdirectory exists.  You may include a drive
  2549.    specification in the subdirectory name.
  2550.  
  2551. Example:
  2552.    CALL SubExist(SubDir$ + CHR$(0), Valid%)
  2553.    IF Valid% THEN
  2554.       PRINT "Subdirectory "; SubDir$; " already exists"
  2555.    ELSE
  2556.       PRINT "Subdirectory "; SubDir$; " does not exist"
  2557.    END IF
  2558.  
  2559. Name: TestPoint
  2560.  
  2561. Type: Video / BIOS
  2562.  
  2563. Description:
  2564.    Tests a point.  This provides support for 80x50 graphics in text mode
  2565.    (SCREEN 0).  A nonzero value will be returned if the point is set.
  2566.  
  2567. Related routines:
  2568.    ResetPoint, SetPoint
  2569.  
  2570. Example:
  2571.    X% = 39
  2572.    Y% = 24
  2573.    CALL TestPoint(X%, Y%, PointSet%)
  2574.    IF PointSet% THEN
  2575.       PRINT "The point is set"
  2576.    ELSE
  2577.       PRINT "The point is reset"
  2578.    END IF
  2579.  
  2580.  
  2581.  
  2582.  
  2583. Name: Time2Int
  2584.  
  2585. Type: Miscellaneous / ANY
  2586.  
  2587. Description:
  2588.    Compresses a time into an integer.  Some accuracy will be lost in the
  2589.    seconds value, which will be made even (odd numbers are rounded down).
  2590.    Hours should be specified using military time (0-23) to avoid ambiguity.
  2591.  
  2592. Related routines:
  2593.    Date2Int, Int2Date, Int2Time, TimeN2S, TimeS2N
  2594.  
  2595. Example:
  2596.    CALL(Hour%, Min%, Sec%, SqzTime%)
  2597.  
  2598. Name: TimeN2S
  2599.  
  2600. Type: String / ANY
  2601.  
  2602. Description:
  2603.    Converts a time from numeric form to a string.  You must reserve at least
  2604.    eight characters for the string.
  2605.  
  2606. Related routines:
  2607.    DateN2S, DateS2N, TimeS2N
  2608.  
  2609. Example:
  2610.    Hour% = 13       ' 1:30:08 pm
  2611.    Min% = 30
  2612.    Sec% = 8
  2613.    TimeSt$ = SPACE$(8)
  2614.    CALL TimeN2S(Hour%, Min%, Sec%, TimeSt$)
  2615.    ' the result will be "13:30:08"
  2616.  
  2617.  
  2618.  
  2619.  
  2620. Name: TimeS2N
  2621.  
  2622. Type: String / ANY
  2623.  
  2624. Description:
  2625.    Converts a time from a string to numeric form.  The seconds part is
  2626.    optional and will be returned as zero if not in the string.
  2627.  
  2628. Example:
  2629.    TimeSt$ = "13:09:42"
  2630.    CALL TimeS2N(Hour%, Min%, Sec%, TimeSt$)
  2631.  
  2632. Name: TInstr
  2633.  
  2634. Type: String / ANY
  2635.  
  2636. Description:
  2637.    Returns the position of the first occurrence of a specified type of
  2638.    character within a string.  You may combine the following character types
  2639.    by adding their codes (which also allows you to search for the opposite of
  2640.    a specified type).
  2641.  
  2642.    Code   Char. Type    Specifications
  2643.  
  2644.      1    Alphabetic    A-Z, a-z
  2645.      2    Numeric       0-9
  2646.      4    Symbolic      (anything not covered by other types)
  2647.      8    Control       (control codes: ASCII 0-31, 127)
  2648.     16    Graphics      (PC graphics codes: 128-255)
  2649.     32    Blank         (a blank space, ASCII 32)
  2650.  
  2651.  
  2652. Example:
  2653.    ChrType% = 2                         ' seek numeric character
  2654.    St$ = "Mesa, AZ 85204"
  2655.    CALL TInstr(St$, ChrType%, Place%)
  2656.    ZipCode$ = MID$(St$, Place%)
  2657.    ' the result will be "85204"
  2658.  
  2659. Example:
  2660.    ChrType% = 1 + 2 + 4 + 8 + 16        ' seek non-blank character
  2661.    CALL TInstr(St$, ChrType%, Place%)
  2662.    IF Place% THEN
  2663.       PRINT "The first non-blank character is at location"; Place%; "."
  2664.    ELSE
  2665.       PRINT "The string contains no non-blank characters"
  2666.    END IF
  2667.  
  2668.  
  2669.  
  2670.  
  2671. Name: UpCase
  2672.  
  2673. Type: String / ANY
  2674.  
  2675. Description:
  2676.    Capitalizes every letter in a string.  This is much faster than the UCASE$
  2677.    function that comes with QuickBASIC.
  2678.  
  2679. Example:
  2680.    CALL UpCase(St$)
  2681.  
  2682. Name: WeekDay
  2683.  
  2684. Type: Miscellaneous / DOS
  2685.  
  2686. Description:
  2687.    Returns an integer which indicates the day of the week, Sunday through
  2688.    Saturday.  The example shows how to convert the result into a string.
  2689.  
  2690. Example:
  2691.    CALL WeekDay(Day%)
  2692.    DayLen% = VAL(MID$("3346535", Day%, 1))
  2693.    DayLoc% = ASC(MID$("ADGKQVY", Day%, 1)) - 64    ' string must be uppercase
  2694.    DayName$ = MID$("SunMonTuesWednesThursFriSatur", DayLoc%, DayLen%) + "day"
  2695.    PRINT "Today is "; DayName$
  2696.  
  2697.  
  2698.  
  2699.  
  2700. Name: WriteBitF
  2701.  
  2702. Type: Miscellaneous / ANY
  2703.  
  2704. Description:
  2705.    Provides support for arrays of arbitrary bit length (1-8 bits).  The index
  2706.    may range 0-65,535 (use a long integer for indices of over 32,767).  The
  2707.    numbers are compressed into an ordinary integer array.  Since each integer
  2708.    can hold 16 bits, you can calculate the size to which to DIMension the
  2709.    integer array as follows:
  2710.  
  2711.    ArraySize% = CINT((BitArraySize% * BitLength%) / 16! + .5)
  2712.  
  2713. Related routines:
  2714.    ReadBitF
  2715.  
  2716. Example:
  2717.    REDIM Array%(1 TO ArraySize%)
  2718.    DSeg% = VARSEG(Array%(1))
  2719.    DOfs% = VARPTR(Array%(1))
  2720.    CALL WriteBitF(DSeg%, DOfs%, Index%, BitLength%, Value%)
  2721.  
  2722. Name: Xlate
  2723.  
  2724. Type: String / ANY
  2725.  
  2726. Description:
  2727.    Translates each character of a string using a specified table.  The
  2728.    translation table is given as a 256-character string, where each string
  2729.    location contains the value to which to convert the corresponding ASCII
  2730.    code (CHR$(0) is translated to MID$(XlateTable$, 1, 1), and so on).
  2731.  
  2732. Example:
  2733.    XlateTable$ = ""
  2734.    FOR Init% = 0 TO 255                            ' set up do-nothing table
  2735.       XlateTable$ = XlateTable$ + CHR$(Init%)
  2736.    NEXT
  2737.    FOR Init% = ASC("A") TO ASC("Z")                ' uppercase to lowercase
  2738.       MID$(XlateTable$, Init% + 1, 1) = CHR$(Init% + ASC("a") - ASC("A"))
  2739.    NEXT
  2740.    ' The above setup routine would be at the start of your program.
  2741.    ' The below routine runs a string through the translator, in this example
  2742.    ' converting uppercase characters to lowercase.
  2743.    CALL Xlate(St$, XlateTable$)
  2744.  
  2745.  
  2746.  
  2747.  
  2748. Name: XmPrint
  2749.  
  2750. Type: Video / BIOS
  2751.  
  2752. Description:
  2753.    Combines the Xlate and MPrintC routines.  The specified character is run
  2754.    through a translation table and printed to the screen (unless the result
  2755.    is CHR$(0), in which case the character is not printed).
  2756.  
  2757. Related routines:
  2758.    MPrintC, Xlate
  2759.  
  2760. Example:
  2761.    CALL XmPrint(Ch$, XlateTable$, Col%, Row%)
  2762.    LOCATE Row%, Col%
  2763.    ' Note that the row and column are -returned-, not initially specified.
  2764.    ' They are also in reverse order from the usual Microsoft format.
  2765.  
  2766. Name: XQPrint
  2767.  
  2768. Type: Video / CLONE
  2769.  
  2770. Description:
  2771.    Displays a string directly to the screen, very quickly.  Control codes are
  2772.    not translated and will always show up as graphics characters.  You must
  2773.    specify which display page to use and the color (which is calculated by
  2774.    the CalcAttr routine).  This routine does not update the cursor position
  2775.    and must be used in text mode (SCREEN 0).
  2776.  
  2777. Related routines:
  2778.    QPrint, XQPrintD
  2779.  
  2780. Example:
  2781.    St$ = "This is a test of fast screen printing"
  2782.    Row% = 10
  2783.    Col% = 20
  2784.    Page% = 0
  2785.    ForeGnd% = 0        ' let's use reverse video
  2786.    BackGnd% = 7
  2787.    CALL CalcAttr(ForeGnd%, BackGnd%, Attr%)
  2788.    CALL XqPrint(St$, Row%, Col%, Attr%, Page%)
  2789.  
  2790.  
  2791.  
  2792.  
  2793. Name: XQPrintD
  2794.  
  2795. Type: Video / CLONE
  2796.  
  2797. Description:
  2798.    Just like XQPrint, but writes directly to the screen without snow
  2799.    suppression.  This makes it much faster, but means that it will cause
  2800.    flickering on some obsolete CGA displays.
  2801.  
  2802. Related routines:
  2803.    QPrint, XQPrint
  2804.  
  2805.                             New file I/O routines
  2806.  
  2807.  
  2808.  
  2809. This contains some general information about the ADVBAS file I/O routines:
  2810. FClose, FCreate, FOpen, FRead, FSetEnd, FSetRec, and FWrite.
  2811.  
  2812. These routines essentially duplicate a number of existing BASIC statements.
  2813. They are useful, however, for a number of reasons.  They provide you with
  2814. low-level control over the details of file input and output.  They may be
  2815. readily used in subprograms, since they return error codes rather than
  2816. relying on error trapping.  This is important, since BASIC error trapping
  2817. (ON ERROR GOTO) makes your program much larger and slower, and is not
  2818. designed for use within subprograms in any event.
  2819.  
  2820. These routines provide access to the file locking capabilities of MS-DOS 3.0
  2821. and above, allowing you to create programs which work properly on networks
  2822. and in multitasking environments.  Unlike QuickBASIC, the routines will work
  2823. with older versions of DOS even if you use file locking, although of course
  2824. they won't provide the networking/multitasking capabilities that old DOS
  2825. versions lack.
  2826.  
  2827. When you open a file in BASIC, you give the file a number.  From that point
  2828. on, you always refer to that file by the same number, until you CLOSE it.
  2829. With the ADVBAS routines, you don't give the file a number-- instead, the
  2830. number (a "handle") is returned to you by the routine.  This frees you from
  2831. having to worry about whether the number you specified is already in use.
  2832.  
  2833. In BASIC, when you open a file for OUTPUT or RANDOM access, the file is
  2834. automatically created, or deleted and recreated if it already exists.  The
  2835. ADVBAS routines will not automatically create (or delete) files unless you
  2836. use the FCreate routine.  This helps guard against unexpectedly annihilating
  2837. existing files.
  2838.  
  2839. Like BASIC, you must CLOSE a file when you are finished using it.  Unlike
  2840. BASIC, this is not done automatically for you when the program ends-- you
  2841. must use the FClose routine, or your file(s) may not be properly updated.
  2842.  
  2843. The ADVBAS file routines are not restricted to specific modes the way BASIC
  2844. is.  You can use them on sequential or random files, text or binary files, or
  2845. for that matter, devices.  Every time you read from or write to a file, the
  2846. file pointer is updated to point to the next file location (like BASIC
  2847. sequential files)... but if you prefer, you can set the file pointer to a
  2848. specific location (like BASIC random-access files).
  2849.  
  2850. The ADVBAS file routines do not provide critical error handling, which copes
  2851. with serious disk problems (such as leaving the drive door open on floppy
  2852. drives).  They do support the critical error handler provided by BASIC when
  2853. you compile with error trapping turned on, however.
  2854.  
  2855.                             New file I/O routines
  2856.  
  2857.  
  2858.  
  2859. Here are the more common error codes returned by the file routines:
  2860.  
  2861.        -1    Unable to read or write the entire record
  2862.         2    File not found
  2863.         3    Path not found
  2864.         4    No handle available
  2865.         5    Access denied
  2866.         6    Invalid handle
  2867.        15    Invalid drive specification
  2868.  
  2869. If you get a "no handle available" error, you have run out of room to open
  2870. files.  You can increase this to some extent by adding an appropriate
  2871. "FILES=xx" statement to your CONFIG.SYS.  If this doesn't help and you really
  2872. need to have all those files open at once, you can gain extra file handles by
  2873. using FClose on some of the predefined system file/device handles:
  2874.  
  2875.         0    stdin     standard input  (do not close this one)
  2876.         1    stdout    standard output (do not close this one)
  2877.         2    stderr    standard error output (probably safe to close)
  2878.         3    stdaux    comm port #1    (usually safe to close)
  2879.         4    stdprn    printer port #1 (usually safe to close)
  2880.  
  2881. The comment "usually safe to close" means that this handle is not used by
  2882. QuickBASIC and can be closed and re-used by your program unless you have a
  2883. specific need to access that handle.  QuickBASIC has its own communications
  2884. and printer handlers which do not rely on DOS, so it's almost always safe to
  2885. close handles 3 and 4, which will gain you access to two more file handles.
  2886.  
  2887. See your DOS manual for further information on files and CONFIG.SYS.
  2888.  
  2889.                             Bugs in BASIC Compilers
  2890.  
  2891.  
  2892.  
  2893.  
  2894. QuickBASIC 1.0:
  2895.  
  2896. If there is not enough memory when you try to execute the SHELL command, your
  2897. program will crash.
  2898.  
  2899. The error STRING FORMULA TOO COMPLEX appears erratically in some programs,
  2900. for no apparently good reason.
  2901.  
  2902.  
  2903. QuickBASIC 1.02:
  2904.  
  2905. This release solves the SHELL crash problem.  Also, more control
  2906. characters are handled in the same manner as the BASIC interpreter.  Many
  2907. miscellaneous problems have been fixed... but not the mysterious and deadly
  2908. STRING FORMULA TOO COMPLEX error.
  2909.  
  2910.  
  2911. QuickBASIC 2.0 - 3.0:
  2912.  
  2913. If your program uses error trapping, it must have at least one line number
  2914. in the program, even you normally only use labels.  Otherwise the program
  2915. will crash if it runs into an error.
  2916.  
  2917. Screen paging doesn't work in QB 2.0.
  2918.  
  2919. If you have a REMark on the same line as a DATA statement, you'll get a
  2920. series of peculiar error messages.
  2921.  
  2922. Compiling programs which use libraries from the editor/environment produces
  2923. flaky code.  This does not affect compiling from the command line, however.
  2924.  
  2925.                             Bugs in BASIC Compilers
  2926.  
  2927.  
  2928.  
  2929.  
  2930. QuickBASIC 4.0:
  2931.  
  2932. Dynamic arrays can't be passed to assembly routines in the standard manner.
  2933. This also affects static arrays, but only in the QB editor/environment.  The
  2934. DYNPTR routine has been added to ADVBAS to solve this problem.
  2935.  
  2936. Compiling programs which use libraries from the editor/environment produces
  2937. excessively large programs.  Instead of linking just the appropriate
  2938. routines, QuickBASIC links the entire library to your program.  Due to the
  2939. syntax used, this can also cause the compilation to abort due to having too
  2940. many routines for the linker to cope with.  This does not affect compiling
  2941. from the command line, however, provided that you use the normal syntax
  2942. instead of the bizarre syntax that the QB editor/environment uses.
  2943.  
  2944. When compiling programs which use libraries from the editor/environment, the
  2945. LIB path variable is ignored.  This means that your .LIB files must be in the
  2946. directory in which you are compiling your program.
  2947.  
  2948. Serial communications is buggy.  If you SHELL or do any of a number of other
  2949. things, QuickBASIC is liable to entirely forget about the existence of the
  2950. comm port(s).  In fact, it essentially erases all knowledge of the comm ports
  2951. from the computer.  This can be cured by rebooting the system.
  2952.  
  2953.  
  2954. QuickBASIC 4.1:
  2955.  
  2956. The communications problems have been fixed.
  2957.  
  2958.  
  2959. QuickBASIC 4.5:
  2960.  
  2961. The problems with compiling from the editor/environment have been fixed.
  2962.  
  2963.                                   BASIC Bugs
  2964.  
  2965.  
  2966.  
  2967.  
  2968. You can create files that contain blank spaces using BASIC.  This is a
  2969. problem, since DOS considers the space to be a delimiter, and is entirely
  2970. unable to cope with such files.  Some archive and disk backup programs also
  2971. have trouble with files containing spaces.  Be careful to screen out any
  2972. spaces before creating files!  Note that this also applies to subdirectories,
  2973. which are really only a kind of specialized file.
  2974.  
  2975. If you convert a string to a number using the VAL function, you expect the
  2976. conversion process to end at the end of the string or at the first
  2977. non-numeric character.  Unfortunately, BASIC does not consider spaces to be
  2978. non-numeric, with the result that a string like "256 12" is not converted to
  2979. 256, as you would expect, but to 25612.  Microsoft's representatives on
  2980. CompuServe do not consider this to be a bug, although it's hard to think of
  2981. an application in which such behavior might be appropriate.
  2982.